***** Build ***** .. highlight:: bash Overview ======== Install a C build toolchain:: sudo ./installc The installer installs missing packages only and 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. :command:`./configure` is controlled by: * Configuration files (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* and the :file:`Makefile` conform 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:`conf/siterc`, which is always loaded and never included in a distribution. .. tip:: You can create a separate development configuration with:: ./configure --conf=develrc --makefile=devel.mk And use that configuration with:: make -f devel.mk 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` Compile-time configuration ========================== Some aspects of the behaviour of Para can be configured at compile-time by defining one or more of the macros below. ========================== ============= ========= ================================ Macro Type Default Description ========================== ============= ========= ================================ :c:macro:`COV` bool [#bool]_ 0 Build for coverage reports? :c:macro:`DEF_GRACE` double 0 Default for :option:`-k` :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 [#bool]_ 0 [#cfg]_ Is :manpage:`getloadavg(3)` available? :c:macro:`NAUTOTESTS` bool [#bool]_ 0 Disable auto-generated tests? :c:macro:`NDEBUG` bool [#bool]_ 1 [#dev]_ Disable assertions? :c:macro:`EXTENSIONS` bool [#bool]_ 0 [#prd]_ Enable non-standard features? :c:macro:`LINT` bool [#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 [#bool]_ 0 Include :file:`para.c` as header? [#test]_ :c:macro:`PARA_C_AS_OBJ` bool [#bool]_ 0 Compile :file:`para.c` as object? [#test]_ ========================== ============= ========= ================================ Use *configure*'s :option:`-D` flag to define 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 processors if :c:macro:`_SC_NPROCESSORS_ONLN` is available. .. [#cfg] Detected by :command:`./configure`. .. [#ncfg] Only controls which floating-point exception tests are run. .. [#dev] 0 when using the development build configuration. .. [#prd] 1 when using the production or the development build configuration. .. [#null] Including the null terminator. .. [#test] For compiling unit tests. 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. check Compile and run tests. quickcheck Only compile and run quick tests. lint Run Flawfinder_, RATS_, Clang-Tidy_ and Cppcheck_. quicklint Only run Flawfinder_ and RATS_. memcheck Run Valgrind_ or leaks_. dist Make a distribution tarball. distcheck Run :command:`make all lint check memcheck installcheck` from a tarball. install Install Para. installcheck Check whether `make install` works. uninstall Uninstall Para. tidy Delete backups, logs, and temporary files. mostlyclean :command:`make tidy` and delete binaries, coverage data, and objects. clean :command:`make mostlyclean` and delete coverage reports. mrproper :command:`make clean` and delete caches, tags, and tarballs. distclean :command:`make mrproper` and delete the build configuration. maintainer-clean :command:`make distclean` and delete X macros, the manual, and some documentation. ================ ============================================================ Troubleshooting =============== :command:`./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 Known Issues ============ Some versions of the Public Domain Korn Shell cannot run :command:`./configure`.