Quick How-To for "Abc"

2022-05-16


Note: This is a "quick how-to". The instructions are subjectively reduced to a minimum, to keep focus and clarity.


Setup for every new project-tree


[1] Create configuration files for projects and subprojects.

  • Create the "abc.conf" configuration file in the top-level project directory.
  • For each sub-project:
    • (optional) If there is already a known make/ninja/cmake file, then a fresh "abc.conf" will be copied automatically from main config directory.
    • OR you can create "abc.conf" now.
  • (optional) Fine-tune "abc.conf" for each sub-project.

[2] Generate the make/ninja/cmake files for the whole project tree.

  • Run once abc in top-level project directory.
  • Alternative: run abc --help and pick a generator.


Now the projects can be build as usual.

  • Run make orninja or cmake, according to the generator you have chosen, in the top-level project directory.


Setup for the first time


[1] Unpack the archive:

unzip -o __ARCHIVE__.zip OR 7z x -y __ARCHIVE__.zip

(optional) Verify the checksums against the official checksum values.

Do not use checksums from unknown sources.

(optional) On Linux: chmod +x bin/* or chmod u+x bin/*.


[2] Unpack the archive with Abc main config files.

Abc looks for its directory name in:

  • Upper directory from CWD.
  • Location of abc executable.
  • HOME directory on Linux, HOMEDRIVE/HOMEPATH on Windows.


Special case: if "abc" executable is renamed to "xyz" (just an example),

  • then it first looks for a directory named "xyz",
  • else it falls back to the usual directory name "abc".


Examples:

  • Say your work directory is "dir1" and your top-level projects are in "dir1/proj1", "dir1/dir2/proj2".
  • If multiple users are using the same computer for development, then a good location for main configuration directory is "dir1/abc".
  • If only you will use the computer for development, then a good location for main configuration directory can be "$HOME/abc".
  • If only you will use the computer for development, another good location can be "dir1/abc", and development stuff into "dir1" will use "dir1/abc".
  • Your choice.


[3] Adapt Abc main config files to your needs.

Use your compiler and your flags. The sample config files are commented. These ~could~ straightly work if gcc and linux tools (bash, ls, rm, etc.) are properly configured in a "standard" way (which standard?). On Windows, this is also possible.


Notes:
  • Abc is not limited to C/C++. Other languages can be defined, as long as the compile & link steps are properly adapted.
  • Scripts or user apps can extend the functionality. One important goal is to have a reliable build: from start up to install and delivery steps. However this goal depends on the user needs and skills to do it. The user may choose in its scripts/tools to send a success/fail status email at a specific build level, for example. Build output can be configured by the user, for example with "runcaplog" tool.


[4] Create "abc.conf", a local config file, in top-level project.

Eventually, if needed, fine-tune a sub-project with its own local config file.


[5] Init for the top level project (and sub-projects).

  • Once: run abc in this directory. Alternative: run abc --help and pick a generator.


Notes:
  • "make" is stable.
  • "ninja" is usually faster than "make" and should have been stable. However, on Windows, sometimes ninja cache must be manually cleared by the user. This need-user-intervention is the main reason for the "(e)experimental" label. When the cache is cleared each time, the build time with ninja or make is about the same.
  • "cmake" is slower overall. Its reliability highly depends on: version, how it was installed and additional cmake files. Reliability may be more important than portability or other benefits. However, you can decide which one suits you best.


Now the projects can be build as usual.

  • Run make orninja or cmake, according to the generator you have chosen, in the top-level project directory.
    • There are NO other special steps for Abc.
  • When files are added/removed/changed, the make-files are updated automatically.
  • Sometimes "make distclean" is needed (or "ninja distclean"), especially when projects are removed. For the user to have a chance to detect dependency/disk/LAN issues, clean/distclean were not automatized by default. Rationale:
    • Partial delivery is not allowed.
    • Either everything is ok (including tests, coverage, etc.), either not.


Additional notes regarding the license file
  • With a "Default License", there is usually a small delay for each project.
    • Delays can add up quickly when more than one project is used.
  • No delays during Happy Hours.
  • You can purchase an "Active License" to eliminate delays.

Next Article

..