diff options
Diffstat (limited to 'docs/en/erlang.mk/1/guide/ports.asciidoc')
-rw-r--r-- | docs/en/erlang.mk/1/guide/ports.asciidoc | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/docs/en/erlang.mk/1/guide/ports.asciidoc b/docs/en/erlang.mk/1/guide/ports.asciidoc new file mode 100644 index 00000000..02c636fd --- /dev/null +++ b/docs/en/erlang.mk/1/guide/ports.asciidoc @@ -0,0 +1,100 @@ +[[ports]] +== NIFs and port drivers + +Erlang.mk can not only build Erlang projects, but also the C code +that some projects come with, like NIFs and port drivers. + +There are two ways to build the C code: using a custom Makefile, +or making Erlang.mk do it directly. The C code will be built +as needed when you run `make`. + +// @todo something for easier bootstrapping + +=== C source code location and Erlang environment + +The C source code should be located in the '$(C_SRC_DIR)' directory. +It defaults to 'c_src/'. Should you need to modify it, all you +need to do is to set the variable in your Makefile before including +Erlang.mk: + +[source,make] +C_SRC_DIR = $(CURDIR)/my_nif_source + +When this directory exists, Erlang.mk will automatically create a +file named '$(C_SRC_ENV)'. This file defaults to '$(C_SRC_DIR)/env.mk'. +This can also be changed: + +[source,make] +C_SRC_ENV = $(C_SRC_DIR)/erlang_env.mk + +It contains a few variable definitions for the environment used for the build: + +`ERTS_INCLUDE_DIR`:: + Path to the ERTS include files ('erl_driver.h', 'erl_nif.h' and more). +`ERL_INTERFACE_INCLUDE_DIR`:: + Path to the Erl_Interface include files ('ei.h' and related). +`ERL_INTERFACE_LIB_DIR`:: + Path to the Erl_Interface static libraries. + +=== Using a custom Makefile + +Erlang.mk will automatically run `make` if it detects a Makefile +in '$(C_SRC_DIR)/Makefile'. + +The Makefile should have at least two targets: a default target +(which can be anything, for example `all`) which is invoked when +building the C code, and a `clean` target invoked when cleaning +it. + +You can include the 'env.mk' file to benefit from the Erlang +environment detection: + +[source,make] +include env.mk + +=== Using Erlang.mk directly + +You don't need to write a Makefile to build C source code, however. +Erlang.mk comes with rules to build both shared libraries and +executables, using the source files it finds in '$(C_SRC_DIR)'. + +By default, Erlang.mk will create a shared library. To change +this and create an executable instead, put this in your Makefile +before including Erlang.mk: + +[source,make] +C_SRC_TYPE = executable + +The generated file name varies depending on the type of project +you have (shared library or executable) and on the platform you +build the project on. + +For shared libraries, the generated file name will be +'$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)', with the default +being '$(CURDIR)/priv/$(PROJECT)' followed by the extension: +`.dll` on Windows, `.so` everywhere else. + +For executables, the generated file name is +'$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)', with the same +default except for the extension: `.exe` on Windows, and otherwise +nothing. + +Erlang.mk sets appropriate compile and linker flags by default. +These flags vary depending on the platform, and can of course +be overriden. + +`CC`:: + The compiler to be used. +`CFLAGS`:: + C compiler flags. +`CXXFLAGS`:: + C++ compiler flags. +`LDFLAGS`:: + Linker flags. +`LDLIBS`:: + Libraries to link against. + +The source files are automatically gathered from the contents +of '$(C_SRC_DIR)'. Erlang.mk looks for '.c', '.C', '.cc' and '.cpp' +source files. You can define the variable `SOURCES` to manually +list the files to compile. |