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_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.

  • A recommended test.C file implements functional and non-regression tests.

    • Tests are run in the top level directory (not in ./src).
    • The make test commands compiles and run the tests.
    • The tests are compiled in the ../node_modules/.bin/test executable.

  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 test
  

  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 += :../build/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 top level directory (not in ./src).

(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.

  • Any .mpl, i.e., maple, file is executed in the ./public directory to generate optional graphic or text files, as programmed in the the maple source code.

(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.
    • The test.C file, if any, contains a int main() routine and is compiled and executed for test
      • make test ARGV="arg1... " runs interactive tests.
        • Tip: run make test ARGV="-i" if no special options for interactive tests.
      • make gtest [ARGV="arg1... "] runs C/C++ tests via gdb, in order to observe debugging information.
      • make vtest [ARGV="arg1... "] runs C/C++ tests via valgrind, with standard options, in order to observe debugging information.
    • The test.js file, if any, is run with node.
    • The test.html file, if any, is opened using current $BROWSER defined browser to run tests via HTML code.
    • User defined test commands defined in the makefile TEST variable.

  Note: By contract, the test.sh, test.js and test.cpp files run automatically if no argument and in interactive mode if any argument, e.g.:

   make -C ./src test ARGV="arg1 ..."
  

(static) clean()

Description:

• Cleans installation files.

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

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

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

  • The makefile CLEAN variable allows to define additional clean targets.

(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 and archiving

  • 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.

  • 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).

  • When the npm install command is run, after npm installation, it runs "make -s -C ./src install" which:
    • Updates the .src/.makefile.inc file with all the instruction defined here to use a fresh version.
    • Constructs any target specified in the makefile INSTALL variable in order to perform additional install operation.
    • Runs the ./src/install.sh script if any if order to perform additional install operation.

  Remark: In order to initialize a package directory, runs the init script.