***** Build ***** .. highlight:: bash Overview ======== Install a C build toolchain:: sudo ./installc The installer uses the system's package manager. .. tip:: Use :command:`sudo ./installc -r` to remove the installed packages again. Detect the build configuration:: ./configure Build Para:: make See below for details. Configuration ============= The build configuration is stored in the :file:`Makefile`. The :file:`Makefile` is generated from :file:`Makefile.in` by :command:`./configure`, which replaces defaults with values more appropriate to the system. The configuration detected by :command:`./configure` is saved to :file:`config.status`, the output of feature detection tests to :file:`config.log`. :file:`config.status` is a shell script that rebuilds the :file:`Makefile` using the most recently detected configuration. *Configure* is controlled by: * A configuration file (see Files_ below) * The environment (see Environment_ below) * Arguments (see Arguments_ below) Para does *not* use Autoconf_; *configure* and its configuration files are hand-written shell scripts; so you can debug them if you need to. The same goes for the :file:`Makefile`. However, be careful to edit :file:`Makefile.in`, the template from which the :file:`Makefile` is generated, *not* the :file:`Makefile` itself, or else your changes may get overwritten. *Configure* conforms to the `GNU Coding Standards`_ (chap. 7). Files ----- Para ships with three build configurations, which can be found in the :file:`conf` directory. =============== =============== Filename Purpose =============== =============== :file:`prodrc` Production :file:`develrc` Development :file:`posixrc` Fallback =============== =============== Use :file:`prodrc` for production and :file:`develrc` for development. :file:`posixrc` only tests for compiler flags that are either required by some compilers or defined by POSIX.1-2008_ and disables features that require non-standard interfaces. It is intended as a fallback if Para does not compile with the production build configuration. For example, .. code:: bash ./configure --conf=posixrc selects :file:`conf/posixrc`. Site-specific settings can be put in :file:`.configrc`, which is always loaded. .. tip:: You can create a separate development configuration with:: ./configure --devel --makefile=devel.mk And use that configuration with:: make -f devel.mk Macros ------ ========================== ============= ========= ================================ Macro Type [#bool]_ Default Description ========================== ============= ========= ================================ :c:macro:`COV` bool 0 Build for coverage reports? :c:macro:`DEF_GRACE` double 120 Default for :option:`-g` :c:macro:`DEF_LOAD` double 2.0 Default for :option:`-l` [#cpus]_ :c:macro:`DEF_NJOBS` ptrdiff_t 2 Default for :option:`-j` [#cpus]_ :c:macro:`DEF_TIMEOUT` unsigned int 0 Default for :option:`-t` :c:macro:`HAVE_GETLOADAVG` bool 0 [#cfg]_ Is :c:func:`getloadavg` available? :c:macro:`NAUTOTESTS` bool 0 Disable auto-generated tests? :c:macro:`NDEBUG` bool 1 [#dev]_ Disable assertions? :c:macro:`NEXTENSIONS` bool 0 [#psx]_ Disable non-standard features? :c:macro:`LINT` bool 0 Analyzed by linter? :c:macro:`MAX_NJOBS` ptrdiff_t 64 Maximum for :option:`-j` [#null]_ :c:macro:`MAX_NVARS` ptrdiff_t 256 Maximum number of environment variables [#null]_ :c:macro:`MAX_STR_SIZE` size_t 8192 Maximum string length [#null]_ :c:macro:`PARA_C_AS_HDR` bool 0 Include :file:`para.c` as header? [#test]_ :c:macro:`PARA_C_AS_OBJ` bool 0 Compile :file:`para.c` as object? [#test]_ ========================== ============= ========= ================================ Use *configure*'s :option:`-D` flag to set macros. For example, .. code:: bash ./configure -DMAX_NJOBS=256 configures Para to permit running up to 255 jobs in parallel (one slot is needed for a terminator). .. [#bool] Use 0 for false and 1 for true. .. [#cpus] Overriden by the number of online processors if :c:macro:`_SC_NPROCESSORS_ONLN` is available. .. [#cfg] Detected by *configure*. Always 0 when using the POSIX build configuration. .. [#dev] 0 when using the development build configuration. .. [#psx] 1 when using the POSIX build configuration. .. [#null] Including the null terminator. .. [#test] For compiling unit tests. Environment ----------- *configure* respects the following standard environment variables: ======== ============================================== Variable Purpose ======== ============================================== CC C compiler CPPFLAGS Flags for the C preprocessor CFLAGS Flags for the C compiler LDFLAGS Flags for the linker LDLIBS Libraries to link against DESTDIR Destination directory for staged installations PREFIX Installation directory prefix ======== ============================================== Arguments --------- See the `GNU Coding Standards`_ (chap. 7). However, different to Autoconf_, unrecognised options are passed on to the C compiler if the compiler supports them. .. seealso:: :command:`configure --help` Makefile targets ================ The :file:`Makefile` conforms to the `GNU Coding Standards`_ and supports the following 'phony' targets: ================ ============================================================ Target Description ================ ============================================================ all Alias for "para" and the default target. tidy Delete backups, logs, and temporary files. mostlyclean `make tidy` and delete binaries, coverage data, and objects. clean `make mostlyclean` and delete coverage info. mrproper `make clean` and delete caches, tags, and tarballs. distclean `make mrproper` and delete the build configuration. maintainer-clean `make distclean` and delete X macros and some documentation. dist Make a distribution tarball. distcheck Run `make check lint installcheck` from a tarball. install Install Para. installcheck Check whether `make install` works. uninstall Uninstall Para. ================ ============================================================ Troubleshooting =============== *configure* fails ----------------- Try the POSIX build configuration (see `Files`_ above). If that, too, fails re-direct the output of *configure* to :file:`config.mk` to save the configuration that *is* detected:: ./configure >config.mk Then copy :file:`Makefile.in` to :file:`Makefile`, but uncomment the line ``#include config.mk``:: sed 's/#\(include config.mk\)/\1/' Makefile.in >Makefile Makefile updates ---------------- The `GNU Coding Standards`_ mandate that the Makefile be updated whenever one of the files it depends on changes. Rename or remove :file:`config.status` to disable this behaviour. Manual compilation ------------------ If all else fails, compile :file:`para.c` manually:: c99 -DNDEBUG -O1 -opara para.c