Repository files navigation

The General Utility Library for C++14 (GUL14) contains often-used utility functions andtypes that form the foundation for other libraries and programs. The main fields coveredby the library are:

• String handling
• Concurrency
• Time
• Statistics and numerics
• Debugging
• Containers
• Type traits
• Core guideline support library (GSL) excerpts
• Backports from new standard library extensions

To get started, have a look at thedocumentation website.

Here you find more detailed information on:

• Building
  • Build configuration switches
  • Default Configurations
  • Building on Windows with Visual C++
  • Single header use
• Testing
• Coverage report generation
• Versioning
  • Version number examples

GUL14 is available from thevcpkg package manager. Once you havevcpkg installed, just run:

    vcpkg install gul14

Clone this repository:

    git clone https://github.com/gul-cpp/gul14.git    cd gul14

Use meson to configure the build you want to have. A list of thebuild options is given below. Build directory name can bewhat you want and can even be located outside of the projecte directory. E.g. on Linux youcan place the build directory into a tmpfs mount (aka RAM disk).If your build directories are inside the project root directory and starting with 'build'they will be ignored by git.Examples:

    meson setup <build-dir>    meson setup -D tests=false <build-without-tests-dir>    meson setup --prefix=/usr --buildtype=release <build-rel-dir>    meson setup --buildtype=release --unity=on <build-rel-unity-dir>    meson setup --buildtype=release -D docs=false <build-nodocs-rel-dir>    meson setup -Dcpp_args='-Wconversion -Wshadow' --buildtype=debug <build-with-extra-warnings-dir>    CXX=clang++ meson setup <build-clang-dir>

Typical build configurations can be easily summoned as detailed inDefault configurations below.

Afterwards, enter the build directory – in this case, for the release build – and startthe build process:

    cd <build-dir>    ninja    ninja test    ninja data/docs

If you need one, a Debian package is easily created with(Note 2):

    debuild

Packaging is closely coupled to how version information is extracted (seeVersioning below). The debian/ files including the debian/changelog areautogenerated on configure time. You need to reconfigure your build directory iftags/versions/commits change afterwards.

Notes:

1. The configuration to be changed can immediately follow the-D for example-Dwarning_level=1
2. debuild is the normal Debian packager. For DESY environments, consider usingmakeDdeb instead.
3. It is not necessary to callninja before callingdebuild/makeDdeb. But ofcourse you usually want to runninja test before you package.
4. debuild/makeDdeb has to be called in the build directory of choice (that hasbeen usually created with buildtype = release). Note that a proper Debian packageneeds the prefix to be set to /usr (see examples above)

You can list all possible build configuration switches withmeson configurein an existing build directory [1]. This command can also be used to changebuild configurations after the directory has been created. For example todecrease the warning level after the build directory has already been created:meson configure -D warning_level=1 (Usemesonconf if your meson is tooold.)

A lot of the switches change the versioning behaviour, more information on theversioning is given in aseparate paragraph.

In addition to meson's standard switches there are:

Option         Default Value  Possible Values  Description------         -------------  ---------------  -----------docs           true           [true, false]    Generate documentation via doxygentests          true           [true, false]    Generate testsdeb-dev-name   @0@-dev        string           Debian package name for development packagedeb-name       @0@            string           Debian package namedeb-vers-pack  false          [true, false]    Debian package name will contain versiondeb-vers-tag   v              string           Debian package uses git version tags starting with this

Thedeb-*name switch can be used to configure the debian package buildingprocess with non-standard packet names. The substring '@0@' will be replaced bythe canonical packet name (i.e. 'libgul14'). Although non-standard packagesautomatically conflict with standard packages care must be taken to keep theinstall target system consistent (i.e. install always only one variant oflibgul14).

Thedeb-vers-ext switch forces the package names and versions to be based onthe latest 'git external tag'. This is a tag in the git repository that does notstart with 'v'. It is expected to give the version number to use in the formDESCRIPTION_major_minor_patch, where major, minor, and patch are positiveintegers.

Thedeb-vers-pack switch appends the version number to the library andpackage names. With this multiple different versions of GUL can be installed inparallel.

Thedeb-vers-tag option specifies how git tag start that are considered asversion number tags. Tags selected here shall have a number after their start,in the form[0-9]+[._][0-9]+([._][0-9])?. The actual version is deduced fromthis and the changelog walks the git repository to find previous versions thatfit this pattern. Note that only the startstring is used to identify these tags,that they conform to the given regex is to be ensured by the user.

Overview of maybe useful standard project options:

Option         Default Value         Description------         -------------         -----------prefix         /usr/local            Installation prefixlibdir         lib/...               Library directoryincludedir     include               Header file directorydatadir        share                 Data file (Doxygen website) directory

Some typical build configurations can be set up in build directories underbuild/ withthe following commands:

• make release builds the release version of the library underbuild/x86\_64-linux-gnu/release
• make debug builds the debug version of the library underbuild/x86\_64-linux-gnu/debug
• make doocs-release builds a DOOCS release version that can be packaged with makeDdeb underbuild/x86\_64-linux-gnu/doocs-release
• make test runs unit tests on the release version
• make BUILDTYPE=debug test runs unit tests on the debug version
• make test-junit runs unit tests and generates output in JUnit XML format underbuild/x86\_64-linux-gnu/release/test.xml
• make JUNIT_XML_FILE=a.xml test-junit runs unit tests and generates output in JUnit XML format in the specified file
• make clean cleans up the build files of the release version
• make BUILDTYPE=debug clean cleans up the build files of the debug version
• make mrproper removes all build directories completely
• make doc builds documentation underbuild/x86\_64-linux-gnu/release/resources/doxygenerated (needs Doxygen and Graphviz)
• make localinstall makes a local installation of the library under$HOME/Ubuntu-16.04-x86\_64/lib

GUL can be built with Visual C++, although the integration with the Visual Studio IDE issomewhat patchy. In principle, meson and ninja can be used as outlined above. However,the devil is in the details:

• For Meson, prefer the MSI installer fromhttps://mesonbuild.com/. We found that Mesonversions packaged with the Anaconda Python distribution do not work, to name anexample.
• For Ninja, the version from the Meson MSI installer works just as well as the onedistributed with Visual Studio 2019 (in the cmake workload).

Setting up the PATH and calling the correct executable can be difficult. We distribute aWindows batch filetools\make_vs.bat as an example. It may require some editing toadapt it to your system, but afterwards you can call it from the command line or directlyfrom Visual Studio to initiate a build, cleanup, or to run the unit test suite.

Usage:make_vs mrproper                    - Remove the entire build directorymake_vs release <platform>          - Build the release version of the library for the specified platformmake_vs debug <platform>            - Build the debug version of the library for the specified platformmake_vs test <buildtype> <platform> - Run the unit tests for the specified build type and platformwhere:<buildtype> is one of "release" or "debug"<platform> is one of "x86" or "x64"

The files.vs\tasks_vs.json and.vs\launch_vs.json as well asCppProperties.json in the root directory contain information for Visual Studio 2019that should allow you to open the folder via "open folder" (i.e. without a project file)and still be able to build and debug GUL via the batch file.

It is not possible to build GUL with a version prior to Visual Studio 2017 version 15.7(a.k.a. 19.14), because basic language features aremissing(e.g. two phase name lookup is needed, N3652 and N3653 are used in GUL code).

Under some circumstances it is nice to have all of GUL in only one header file that canbe included - and no library to link to. For example when doing experiments with onlinecompilers.

This is not the recommended way to use GUL, but you can use the scripttools/single_gulto create such a complete header file (without Catch2).

After configuring the build directory one can run all tests by

    ninja test

To see which tests have failed and get other additional information you might want to doinstead

    meson test --test-args '-r junit'

Or for older meson versions

    mesontest --test-args '-r junit'

To generate a coverage report you need to specify-D b_coverage=true on the meson callfor the build configuration. Then after running the tests (see previous paragraph) thecoverage report is generated by

    ninja coverage-html

Depending on the installed coverage tool the targetscoverage-text andcoverage-xml might also be there. To generate a coverage report the packagegcovmust be installed, andlcov/genhtml or(recommended)gcovr (>= 3.1) is used togenerate the HTML pages.

The versioning of libgul can be divided into two entities:

• the API version
• the packet version

The API has a semantic version number. It has a major and a minor number. Majoris increased on non-backward compatible changes to the API, while the minor partis increased when features are added. This results in a API versions like1.7. The API version is hard coded in the main meson.build file, and thegit revision where it is introduced is tagged with an annotated tag likev1.7 - the lower case letterv followed by the API version. Note thatthe 'patch number' of usual semantic versioning schemes is not defined here.

The packet version is determined by the latest annotated git tag, that matches agiven format: It has to start with the string given as deb-vers-tag. Thedefault is to look for tags starting withv, which are the API version tags.To continue with the example of the previous paragraph the build system willlook for the latest tag that starts withv and findsv1.7 extracts theversion identifier (all that follows the deb-vers-tag:1.7).

The packet version needs to take into account that we could have bugfix packets(packets with the same API version). For this purpose the 'patchlevel' or patchnumber is calculated: It is the number of git commits that the current HEAD isseparated from the tagged API version commit. If GUL is packaged directly froma commit with a new deb-vers-tag version this will be zero. If there are forexample 2 bug-fix commits on top, that number will be two.

Example:

bf184c8 (HEAD) bugfix: Do standalone test on string_util.h9990745 Remove some static code analysis warnings8ab1913 tests: Fix time critical tests on Windowsb4b6847 (tag: v1.7) Bump version number to 1.718499a3 to_number: Do less thoroughly random test on ARM...

If we package the HEAD commit, the API version is1.7, the packet version is1.7.3.

While the API version is fixed to tags starting with 'v' (e.g.v3.5) thepacket version can examine a different/custom set of tags (deb-vers-tag option).Normal Debian packets of course have the same (base) version as the API.

So here once again:

The first tag family donates the API version of the package that is in effectstarting with the tagged commit. The version uses semantic versioning, and theformat is defined asv1.2 where 1 is the major, 2 the minor version-part. Italways starts with a lower casev. This tag is cross checked with theproject version number given in the main meson.build file.

Package versioning can be based on that API version tags, or on any other tagsset that start with the same text. Normal packets use the API tags. If anothertag is desired thedeb-vers-tag prefix must be specified.

The package version patchlevel is automatically determined from the number ofcommits since the package version tagged commit, and added where appropriate asthird number.

That tags are used to tag specific points in time when a packet has been createdfrom the project. Its form isname_1.2.3, and again 1, 2, and 3 donateversion number parts, that might or might not be semantic (see recommendedformat in the description of the deb-vers-tags option). These tags can be usedto create packet names in the form libgul14-1-2-3 (with-D deb-vers-pack=true set in meson). Note that thename_ part is ignored andcan be arbitrary, as long as it does not start with lower case 'v'. The amountof numbers is arbitrary and just all_ or. get substituted by- tofit required format.

Here again a patchlevel is determined by the number of commits since the packet version tagged commit, and added where appropriate as either a semantic versioning patchlevel (i.e. third number) or explicit patchlevel (i.e. addedp<number>)

The packaging rules prevent building dirty repositories. Commit your changes first.

The versioning related switches work in the following way. Assume that the APIversion tag isv0.1 and it is 3 commits behind; and the external tag versionisD_18_11_7 and it is 5 commits behind.

deb-vers-tag   dev-vers-pack    'v'            false            libgul14_0.1.3.deb                       ->   libgul14.so.0.1    'v'            true             libgul14-0-1_0.1.3.deb                   ->   libgul14.so.0.1    'D_'           false            libgul14_18.11.7.p5.deb                  ->   libgul14.so.18.11.7    'D_'           true             libgul14-18-11-7_18.11.7.p5.deb          ->   libgul14.so.18.11.7