make

Methods

(static) build()

Description:

• Build all target files from source files.

  • This corresponds to the npm run build command in the package.json file.

  • User defined build commands are defined in the makefile BUILD variable.

  • This command compiles C/C++ files if any, installs node-gyp files if used, builds the python wrapper if relevant, generates documentation files if possible, and finally builds all target files specified in the BUILD variable of the makefile file.

(static) build_mpl()

Description:

• Compiles Maple files if any.

  • If Maple is available, any .mpl, file is executed in the ./src directory to generate:
    • piece of code translated from algebra derivation, e.g. using the maple2h aidebuild function,
    • graphic defined in the maple source code, e.g. using the maple2jpg aidebuild function,
    • latex formulas or text files, as programmed in the the maple source code, e.g. using the latex Maple function.
  • By contract, all Maple generated files must be added to the git source file bundle, so that if Maple is not available for another checkout instance of the package, generated file are available in a fixed form.
  • These functions are documented as aidemaple static function:
    • New function can be created in aidebuild derived package using, as starting source file:
      • The maple2latex.mpl almost emty function, and
      • The maple2latex.hpp related documentation.
    • A $name function is by contract stored in a $name.mpl file, while tests or other Maple commands are in test.mpl.
    • Any ./src/*.mpl file is run with:
      • The output stored in ./public/*.mpl.out.txt for verification and public share.
        • This file contains errors if any, otherwise contains only the function definition.
      • An uglified version of the file (i.e., of minimal size) stored in ./node_modules/.inc/*.mpl for latter include.
        • Further use simply requires to insert a $include <*.mpl> in the maple source code.
    • Package defined functions can be tested using the test.mpl source file, when running make test.
    • Caveat: Source file comments (which are strongly recommended) must always start a new line, whereas not be added at the end of a maple command line, because maple source file is uglified on one line when included.

(static) build_cpp()

Description:

• Compiles C/C++ files if any.

  Organization of the files and directories

  • C/C++ headers are stored in .hpp files.

  • C/C++ sources yielding library routines are stored in .cpp files.

  • C/C++ main file sources yielding executables are stored in .C files.

  • C/C++ template file sources not taken into account unless explicitely included are stored in .tpp files.

  • Target files are stored:

    • in the ./node_modules/.inc directory for C/C++ include header files of libraries.
    • in the ./node_modules/.lib directory for static C/C++ compiled libraries.
    • in the ./node_modules/.bin directory for binary executable files.

  • The "build_cpp": false directive in the package.json file prevents to compile C/C++ code, even if any.

  • Here we build static ./node_modules/.lib/lib$name.a libraries to simplify the link phase and a better compatibility.

  • The make test commands compiles and run the tests; it is recommended to provide such test.

  Compilation options

  Compilation options include the compiler choice, compilation flags, include directories, precompiled library directories and names, to be defined in the ./src/makefile following the given model:

  CXX      = c++                           # 'CXX'          : defines the C/C++ compiler
  CCFLAGS  = -$option                      # 'defines'      : compilation options
  INCDIRS  = -I$include_dir ...            # 'include_dirs' : source header directories
  LIBDIRS  = -L$library_dir ...            # 'library_dirs' : precompiled library directories
  LIBS     = -l$library ...                # 'libraries'    : libraries to link with the code
  AIDEDEPS = aidesys                       # 'AIDEDEPS'     : other aidebuild packages dependencies
  

  • The CCFLAGS and INCDIRR are used for source file compilation.

  • The LIBDIRS and LIBS are used for executable linking.

  • The AIDEDEPS list aidebuild packages dependencies, allowing to automatically builds them.

  • Note: Actually the -std=c++17 C++ standard is in use.

  Compiling with an alternative compiler

  Using this piece of makefile it is possible to erase all C/C++ compilation and recompile with an alternative compiler, here using, for instance, the usual MacOS clang compiler.

  export CXX = clang++
  
  recompile:
   /bin/rm -rf ../node_modules/.lib/*.a ../node_modules/.bin/test
   make build_cpp
  

  Development hints

  • This command allows to identified undefined symbols (i.e., defined in a .hpp fils but not implemented in a .cpp file)

  nm -C --demangle --undefined-only ../node_modules/.lib/$module_name.a | grep $module_name
  

(static) build_gyp()

Description:

• Compiles the node-gyp wrapper files, in order use the code via a web service.

  • The node-gyp wrapping allows to use C/C++ source in a Javascript server side node express utilities for web applications and services.

  • It is based on gyp and napi.

  • It is detailed in the aideweb package, which is a root package for such functionality, e.g. using a WrapperCCService.

  • It is recommended to install gyp globally, to save local space, i.e. run:

  sudo npm install -g node-gyp
  

  • You may also run sudo npm install -g bindings express express-fileupload node-addon-api instead of locally.

  • The "gypfile": true directive in the package.json file enables node-gyp built.

(static) build_python()

Description:

• Builds a python wrapper for the local C/C++ source code and its dependencies.

  • It is based on swig and available as a user adaptable script.
  • The "swig": true directive in the package.json file enables building the python wrapper.
  • The python 3.10 and 3.11 versions are actually usable, easily adaptable to others.

  Development hints

  • In the makefile, you likely have to explicitly list, in the right order, used *.hpp files used by other files because the default .hpp order is random. This is to be done in the PY_HPP file, e.g.,

  PY_HPP="../node_modules/wjson/src/Value.hpp ../.."
  

  A minimal python wrapping is exemplified in this test.py file.

  • In order to avoid, in .hpp or .cpp file, to take python incompatible pieces of code (e.g., C++ operator) into account a construct of the form can be used:

  #ifndef SWIG
  // Here is code not to be wrapped for python by swig
  #endif
  

  • As for usual C/C++ compilation .hpp and .cpp files are taken into account but .tpp are not unless explicitly included.

  • The makefile specifies the PYTHONPATH environment variable allowing to load the defined modules

  export PYTHONPATH += :../node_modules/python/site-packages
  

  • Since SWIG does NOT consider namespace, all objects are prefixed with the compiled module name, e.g.:

  python
  >>> import wjson
  >>> wjson.alert(True, "", "Looks fine") # even if aidesys::alert comes not from wjson but the aidesys namespace
  

  • A recommended test.py file implements functional and non-regression tests.
    • Tests are run in the ./src directory.

(static) build_public()

Description:

• Compiles all documentation and downloadable web files.

  • This generates a HTML documentation in the ./public directory and generates the README.md.

  • Refer for jsdoc2 for a presentation of the general mechanism.

  • The following generation process is performed:

    • The README.md file in automatically generated from the package.json and beyond standard meta-data options:
      • An optional introduction.md allows to present the package in the README beyond meta-data presentation
      • An optional usage section in the package.json as exemplified here allows to add a sequence of HTML lines to described the package usage.
    • All .hpp .js .sh, source files are parsed using jsdoc in order to generate the relative documentation files.
      • Please refer as a .hpp example to this file and notice that the documentation is completely separated from the C/C++ code, which is not parsed by jsdoc.
      • Please refer as a .js example to this file.
      • Please refer as a .sh example to this file noticing that documentation lines are prefixed with #.
    • All .js .css .hpp .cpp .sh are shared after being beautified in order to have a standard format and normalized presentation.
    • Broken links are detected.

  • The following complementary files are processed:

    • All .js and .css are compacted and copied in order to be optimally downloaded.
    • All .html, and .png, .jpg, .gif images are copied in the public directory.
    • Any .odg drawing is translated to .png if libreoffice is installed, and the source is copied.
    • Any .tex (except *.inc.tex input file that only to be included) section file is
      • concatenated to this preamble to be compiled as a .pdf file;
      • with a bibliography using .bib file added if any \cite{…} command are present;
      • usually structured in \subsection to be reused in larger documents,
        • you may refer to this source example compiled here.

(static) test()

Description:

• Runs functional and non-regression tests.

  • This corresponds to the npm test command in the package.json file.

  • The following tests are performed in this order:

    • The test.sh file, if any, is run with bash in the ./src directory.
    • The test.C file, if any, contains a int main() routine and is compiled and executed for test
      • make test [MAIN=test] [ARGV="arg1... "] runs
        • If [MAIN=test] (default) runs Bash + C/C++ + JavaScript + Python tests.
      • make gtest [MAIN=test] [ARGV="arg1... "] runs C/C++ tests only, via gdb, in order to observe debugging information.
        • The following commands are issued: break exit ; run $ARGV ; backtrace ; backtrace all ; quit 0 so that if the program is terminates with errors, the exit stack is shown.
      • make vtest [MAIN=test] [ARGV="arg1... "] runs C/C++ tests only, via valgrind, with standard options, in order to observe debugging information.
    • The test.js file, if any, is run with node.
    • The test.py file, if any, is run after build_python.
    • Constructs any target specified in the makefile TEST variable.

  Note: The ARGV applies to test.sh, test.c and test.js files.

(static) clean()

Description:

• Cleans installation files.

  • This corresponds to the npm run clean command in the package.json file.

  • Removes the ./node_modules and ./package-lock.json directory and file.

  • Also remove all temporary *~ files generated by source normalization (uncrustify command) or esp32gpiocontrol updates, …

  • Runs the ./src/clean.sh script, in the ./src directory, if any, if order to perform additional clean operation.

  • Constructs any target specified in the makefile CLEAN variable.

(static) sync()

Description:

• Syncs, thus publishes, the files with respect to the git repository, and get the npmjs repository status.

  • Runs git pull, commit and push with default options and no commit message (which is only acceptable for preliminary development or minor changes not worth documenting them).

  Publishing on the npmjs repository

  • To publish on https://www.npmjs.com:
    • Set the package.json boolean field "npm_publish": true to indicate that the software has been published.
    • Sign up or Sign in.
    • In the package root directory with package.json:
      • npm adduser to connect the package to the account,
      • npm publish --access-public to publish, while precisions are given if required.
  • To update a published package on https://www.npmjs.com:
    • Properly update the version number in package.json according to semantic-versioning.
    • In the package root directory run npm publish.
  • Managing conflicts: most ofter conflicts are related to generated files, using git merge --autostash (with care) solves the conflict, preserving local source changes.

  Archiving on the softwareheritage

  • To archived on https://archive.softwareheritage.org
    • Set the package.json boolean field "softwareheritage": true to indicate that the software has been archived.
    • Use this link to save it.
      • Enter git in Origin type
      • Enter the documentation link, e.g. https://gitlab.inria.fr/line/aide-group/$projet-name in Origin Url

(static) show()

Description:

• Opens the documentation page using the current defined browser in the $BROWSER variable.

(static) usage()

Description:

• Shows the makefile usage, which is the default operation unless the makefile defined another.

(static) install()

Description:

• Installs specific any source file, this is usually not called directly, but via npm install.

  • When the npm install command is run, after npm installation, it runs make -s -C ./src install which:
    • Updates the .src/.makefile.inc file from internet.
    • Runs the ./src/install.sh script with bash -e in the ./src directory if any.
    • Constructs any target specified in the makefile INSTALL variable. Remark: In order to initialize a package directory, runs the init script.