C/C++ Build and Workflow Support

This repository is designed for inclusion in C/C++ projects for easy build and workflow integration, intended for use in ongoing projects at Adequate Systems, LLC.

Instructions

NOTE: This repository contains it's own LICENSE.md and README.md files that may introduce artifacts in existing files of the target repostiory. Please ensure the LICENSE.md and README.md files are appropriate and/or correct for your target repostiory pulling this repository.

To include or update, it makes no difference; add this repository as a remote and pull the latest (or desired) revision, specifying to "allow unrelated histories"...
^{Adding the repository as a remote may be omitted if previously performed}

git remote add build-c https://github.com/adequatesystems/build-c.git
git pull build-c main --allow-unrelated-histories

Fix merge conflicts and commit with...
^{Commit may also be performed selectively}

git add <any files with merge conflicts>
git commit -m "merge latest build-c repository files"

To upgrade/downgrade at a later date...
^{Recommend using version tags like "build-c-"}

git pull build-c build-c-1.1.2
git add <any files with merge conflicts>
git commit -m "merge build-c v1.1.2 repository files"

Typical active project directory structure

# Configuration / Static
+ Manually managed
- Automatically managed
! Automatically generated only

# base-c
# ├── .github
# │   ├── docs
# │   │   ├── .nojekyll
# │   │   ├── config
# │   │   ├── layout.xml
# │   │   └── style.css
# │   └── workflows
# │       ├── codeql.yaml
# │       └── tests.yaml
- ├── build
- │   ├── bin
- │   │   ├── alternate-binary
- │   │   └── main-binary
- │   ├── test
- │   │   ├── sourcetest-cu.d
- │   │   ├── sourcetest-cu.o
- │   │   ├── sourcetest-cu
- │   │   ├── sourcetest.d
- │   │   ├── sourcetest.o
- │   │   └── sourcetest
- │   ├── source
- │   └── source.cu.o
- │   ├── source.d
- │   └── source.o
! ├── docs
! │   └── htmlfiles...
! ├── include
! │   └── submoduledirs...
+ ├── src
+ │   ├── bin
+ │   │   ├── alternate-binary.c
+ │   │   └── main-binary.c
+ │   ├── test
# ├── │   ├── _assert.h
+ │   │   ├── sourcetest-cu.c
+ │   │   └── sourcetest.c
+ │   ├── source.c
+ │   ├── source.cu
+ │   ├── source.cuh
+ │   └── source.h
# ├── .gitignore
# ├── CHANGELOG.md
# ├── GNUmakefile
# ├── LICENSE.md
# ├── README.md
# └── VERSION

Automatically configured filename/extension support

By default, the GNUMakefile is automatically configured to operate with the following filenames and extensions:

• src/*.c: C source file, compiled with $(CC)
• src/*.h: C header file, for inclusion by other source files
• src/*.cu: CUDA source file, compiled with $(NVCC)
• src/*.cuh: CUDA header file, for inclusion ONLY by other CUDA source files
• src/bin/*.c: C source file, for binary execution
• src/test/component-*.c: C source file for testing C functions
• src/test/component-*-cu.c: C source file for testing CUDA functions, compiled with $(CC) ONLY if $(CFLAGS) contains the "-DCUDA" definition

Makefile usage

CLI usage information is revealed with the use of make or make help in the project's root directory.

Usage:  make [options] [FLAGS=FLAGVALUES]

	make               prints this usage information
	make all           build all object files
	make allcuda       build all CUDA object files
	make clean         removes build directory and files
	make cleanall      removes (all) build directories and files
	make coverage      build test coverage file
	make docs          build documentation files
	make library       build a library file containing all objects
	make report        build html report from test coverage
	make sublibraries  build all library files (incl. submodules)
	make test          build and run tests
	make test-*        build and run sub tests matching *
	make variable-*    show the value of a variable matching *
	make version       show the git repository version string

Configurable Flags

Most parameters used by the Makefile can be configured, either directly in the Makefile itself or on the command line by appending the flag and its value to the call to make. For a complete list of FLAGS it is recommended to peruse the GNUmakefile source.

Integrated Documentation

Requires at least doxygen v1.9.x (unavailable through apt on Ubuntu 20.04)

C/C++ Documentation is made available with the help of Doxygen, using special comment style blocks before functions and definitions for automatic recognition and compilation into an easy to navigate html documentation front-end.

Use:

• make docs after the code is commented appropriately

Integrated Testing

Test files should be placed in the src/test/ directory as *.c source files. Every test file will be compiled and run as it's own binary. So whether a test is broad or specific, a single test file can only count as a single failure.

Use:

• make test to run all tests, OR
• make test-* to run all tests matching *

Test coverage (local)

^{Note: Local test coverage may be incomplete if tests fail}

Test coverage can be generated locally and viewed via a HTML report (generated separately). lcov is required to generate coverage data.

Use:

• make coverage to generate coverage data, AND
• make report to generate html report from coverage data, OR
• make coverage report to do both in one command

Test coverage (workflow)

Test coverage is also generated automatically by the tests.yaml github workflow and automatically uploaded to CodeCov.io upon success, provided that all tests pass.

In some circumstances test coverage of a brand new repository will fail, specifying that the repository cannot be found. Some causes of this error include:

• being too deadly;
  • I think there is some delay between creating/pushing to a repository and the repository being detectable by CodeCov. In this case, you can simply "re-run" the GitHub Action jobs after some time and it will pass ok.
• repository is private;
  • If the repository is private, one would normally question the necessity of coverage data, and recommend that the "coverage job" be removed from the tests.yaml workflow file. However, if coverage data is deemed necessary, you will need to obtain a CodeCov token from the website for your new repository, add it as a GitHub repository "secret" and include it in the tests.yaml workflow file.

On the rare chance that test coverage remains in a failed state, you may need to manually "activate" a repository on the CodeCov dashboard (website) and "re-run" all jobs again.

Submodule support

Support for submodules is automatically built into the Makefile, provided that:

• the submodules use the same build and workflow structure
• the submodules are added to the include/ directory

Add a submodule

Adding a submodule can be done as part of a larger commit if desired.

cd project-repo
git submodule add <submodule-repo> include/<submodule-name>
git commit -m "add submodule to repostory"

Update a submodule

Operating the Makefile between any of the steps for updating a submodule may result in a misconfigured submodule. It is recommended to complete steps below before operating the makefile. Updating a submodule can be done as part of a larger commit if desired.

cd project-repo
git -C include/<submodule-name> pull origin <main|tag|commit>
git commit -m "update submodule to latest revision"

CUDA support

CUDA compilation of *.c source files is enabled by the Makefile for systems with appropriately installed CUDA Toolkit. The Makefile uses the NVCC compiler in place of the normal compiler (normally gcc) to compile identical object files. By default, the NVCC compiler is assumed to be accessible at the standard cuda toolkit install location /usr/local/cuda/bin/nvcc, however this is configurable via the command line using the NVCC flag like so:

make build/source.o NVCC=/path/to/nvcc

Use:

• make cuda to build all objects with NVCC

License

This repository is licensed for use under an MPL 2.0 derivative Open Source license.
The community is free to develop and change the code with the caveat that any changes must be for the benefit of the Mochimo cryptocurrency network (with a number of exclusions).
Please read the LICENSE for more details on limitations and restrictions.