{"id":17503182,"url":"https://github.com/kingsolomon1954/cpp-bootstrap","last_synced_at":"2026-02-13T15:03:21.824Z","repository":{"id":257829708,"uuid":"860605012","full_name":"KingSolomon1954/cpp-bootstrap","owner":"KingSolomon1954","description":"A pre-canned C++ project layout along with automation, containerized tools and fill-in-the-blanks documentation.","archived":false,"fork":false,"pushed_at":"2025-01-05T01:24:30.000Z","size":5091,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T22:51:20.534Z","etag":null,"topics":["bootstrap","cmake","conan","containers","cpp20","cppcheck","doctest","doxygen","gcov","makefile","sphinx","template-project"],"latest_commit_sha":null,"homepage":"https://kingsolomon1954.github.io/cpp-bootstrap/","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KingSolomon1954.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-20T18:51:57.000Z","updated_at":"2025-01-05T18:12:57.000Z","dependencies_parsed_at":"2024-12-08T11:25:07.929Z","dependency_job_id":"d4e7f374-e7d8-473e-af2d-15598d47e589","html_url":"https://github.com/KingSolomon1954/cpp-bootstrap","commit_stats":{"total_commits":54,"total_committers":4,"mean_commits":13.5,"dds":"0.38888888888888884","last_synced_commit":"914445eae55a38caf17635a9607a274ed75fb13b"},"previous_names":["kingsolomon1954/cpp-bootstrap"],"tags_count":3,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingSolomon1954%2Fcpp-bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingSolomon1954%2Fcpp-bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingSolomon1954%2Fcpp-bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingSolomon1954%2Fcpp-bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KingSolomon1954","download_url":"https://codeload.github.com/KingSolomon1954/cpp-bootstrap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248327863,"owners_count":21085258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrap","cmake","conan","containers","cpp20","cppcheck","doctest","doxygen","gcov","makefile","sphinx","template-project"],"created_at":"2024-10-19T22:14:25.858Z","updated_at":"2026-02-13T15:03:16.756Z","avatar_url":"https://github.com/KingSolomon1954.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!---\nComments here if needed.\n--\u003e\n\n\u003ch1 align=\"center\"\u003eC++ Bootstrap Project\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/92fe4271-e308-45e4-9afc-b049fa4c3e0f\" alt=\"\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nProvides a pre-canned C++ project layout along with automation,\ncontainerized tools and fill-in-the-blanks documentation.\n\u003c/p\u003e\n\n---\n\n[![Build](https://img.shields.io/github/actions/workflow/status/kingsolomon1954/cpp-bootstrap/build.yml)](https://github.com/kingsolomon1954/cpp-bootstrap/actions/workflows/build.yml)\n[![Version](https://img.shields.io/github/v/release/kingsolomon1954/cpp-bootstrap)](https://github.com/kingsolomon1954/cpp-bootstrap/releases)\n[![Coverage](https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fkingsolomon1954.github.io%2Fcpp-bootstrap%2Fcode-coverage%2Fhtml%2Fcode-coverage-badge.yml\u0026query=badge.coverage-percent\u0026suffix=%25\u0026label=coverage)](https://kingsolomon1954.github.io/cpp-bootstrap/code-coverage/html/index.html)\n[![Analysis](https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fkingsolomon1954.github.io%2Fcpp-bootstrap%2Fstatic-analysis%2Freport%2Fstatic-analysis-badge.yml\u0026query=badge.error-count\u0026suffix=%20issues\u0026label=analysis)](https://kingsolomon1954.github.io/cpp-bootstrap/static-analysis/report/index.html)\n\n## Features\n\n- Top level Makefile framework for launching targets\n- Uses [containers](#containerized-tools) for build tools (compiler, CMake, auto-docs, etc)\n- CMake used only for C++ compilation/linking\n- [Production and debug](#simultaneous-production-and-debug-trees) trees\n  in same workspace simultaneously\n- [Setup](#conan-setup) with [Conan](https://conan.io/) v2.0 C++ libary management\n- Configured as a consumer of Conan libraries (not a producer)\n- Also setup for two locally developed internal-only libraries\n- Automated [documentation generation](#documentation-generation) with\n  deployment to GitHub Pages\n- Documentation tools - Sphinx, Doxygen, PlantUML\n- All documentation organized together under a single static website\n- Spell checking on docs, in batch or interactive mode\n- [Doctest](https://github.com/doctest/doctest) unit testing framework\n- [Code coverage](#code-coverage) using [lcov](https://github.com/linux-test-project/lcov)\n- [Static code analysis](#static-code-analysis) via [cppcheck](https://cppcheck.sourceforge.io/manual.html)\n- Single [\"version\"](#versioning) file in top level folder drives all targets\n- Clean unpolluted [top level folder](#project-layout)\n- [GitHub Workflows](#github-workflows) for builds, releases, and\n  document publishing\n\nSee the sample auto-generated project documentation here on [Github\nPages](https://kingsolomon1954.github.io/cpp-bootstrap).\n\n*RedFlame* is used as the name of the hypothetical application\nthat is built.\n\n## Prerequisites\n\n- GNU Makefile\n- Podman or Docker\n- Some typical Linux command line utilities\n\nJump ahead to [Getting Started](#getting-started) if you're so inclined.\n\n## Folder Layout\n\n**Top Level View**\n\n    ├── src/\n    ├── docs/\n    ├── tools/\n    ├── etc/\n    ├── _build/\n    ├── Makefile\n    ├── version\n    └── Readme.md\n\n**Two Level View**\n\n    ├── Makefile\n    ├── Readme.md\n    ├── version\n    ├── src/\n    │  ├── CMakeLists.txt\n    │  ├── main\n    │  │  ├── include\n    │  │  ├── src\n    │  │  ├── utest\n    │  │  └── CMakeLists.txt\n    │  ├── lib-gen\n    │  │  ├── include\n    │  │  ├── src\n    │  │  ├── utest\n    │  │  └── CMakeLists.txt\n    │  └── lib-codec\n    │     ├── include\n    │     ├── src\n    │     ├── utest\n    │     └── CMakeLists.txt\n    ├── docs\n    │  ├── src\n    │  ├── site\n    │  └── docs.mak\n    ├── tools\n    │  ├── cmake\n    │  ├── conan\n    │  ├── containers\n    │  ├── scripts\n    │  ├── static-analysis\n    │  └── submakes\n    └── etc\n       ├── Contributing.md\n       └── License\n\nGenerally conforms to\n[PitchFork](https://github.com/vector-of-bool/pitchfork) project layout.\n\n## Example Usages\n\n### Simultaneous Production and Debug Trees\n\nManage production and debug builds.\n\n```bash\nmake             # build default tree (default is initially debug)\nmake prod        # build production tree, default is still debug\nmake debug       # build debug tree, default is still debug\nmake set-prod    # set production tree to be default - sticky setting\nmake             # build default tree (production tree is default)\nmake debug       # build debug tree, default is still prod\nmake prod        # build prod tree, default is still prod\nmake both        # build both prod and debug trees\nmake both -j     # build both prod and debug trees in parallel\nmake set-debug   # set debug tree to be default - sticky setting\nmake clean       # deletes entire _build folder (removes debug and prod)\nmake clean-debug # removes the debug tree\nmake clean-prod  # removes the prod tree\nmake show-default-build # show the default build type\n```\n\n### Run the Executables\n\nAssuming you have the handy container\n[aliases](#handy-aliases-for-build-container) defined, and you are\nsitting in the top folder, then:\n\n```bash\nbd bin/RedFlame    # run the app out of debug tree\nbp bin/RedFlame    # run the app out of production tree\n```\n\nAlternatively you could exec into the build container.\n\n```bash\npodman exec -it -w /work/cpp-bootstrap gcc14-tools bash\nroot#./_build/debug/bin/RedFlame    # run the debug built app\n# Or if you have the bbash alias defined\nbbash\nroot#./_build/debug/bin/RedFlame    # run the debug built app\n\n```\n\nExecutables are built for the build container's OS, not the host OS,\nand are therefore only runnable on the build container. See discussion\nbelow on [Containers](#containerized-tools). \n\n### Run Unit Tests\n\n```bash\nmake unit-test          # runs unit tests for default build\nmake unit-test-debug    # runs unit tests for debug build\nmake unit-test-prod     # runs unit tests for prod build\nmake unit-test-both     # runs unit tests for prod and debug build\n```\n\nOr directly run a unit test executable. Assuming you have the handy\ncontainer [aliases](#handy-aliases-for-build-container) defined, and\nyou are sitting in the top folder, then:\n\n```bash\nbd bin/lib-codec-ut     # run unit tests for library debug tree\nbp bin/lib-codec-ut     # run unit tests for library production tree\n```\n\nExecutables, in this case unit tests, are built for the build\ncontainer's OS, not the host OS, and are therefore only runnable on the\nbuild container. See discussion below on [Containers](#containerized-tools).\n\n### Build and Examine the Documentation\n\n```bash\nmake docs\nfirefox _build/site/index.html\n```\nSee the same auto-generated documentation here on [Github\nPages](https://kingsolomon1954.github.io/cpp-bootstrap).\n\n## Unit Testing\n\n- Uses [doctest](https://github.com/doctest/doctest)\n- Unit tests are kept separate from source code, even though\n  doctest allows unit test in the source file itself\n- Unconditionally compiles unit tests along with each build\n\n## Versioning\n\n- Single version file in project root, supports repeatable builds\n- Semantic versioning\n\n``` bash\ncat version\n1.0.0\n```\n\n- All built artifacts obtain version information from this one file\n- Auto-documentation and containers use this version file\n- CMake is configured to use this version file\n- In addition, C++ Bootstrap supplies its own `buildinfodefs.cmake` to\n  auto generate additional build info. Versioning is then made available\n  to the application via the [BuildInfo\n  class](https://kingsolomon1954.github.io/cpp-bootstrap/doxygen/html/classLibGen_1_1BuildInfo.html)\n  in lib-gen\n\n``` bash\n\u003e ./bin/RedFlame\nRedFlame v1.0.0-1728572288\n    Built by: root\n    Build date: 2024-10-10T07:58:08-07:00\n    Build epoch: 1728572288\n    Build branch: ProjectRestructure\n    Last commit hash: 932a53f3827f1e1d\n```\n\n## Documentation Generation\n\n- There are pre-canned auto documentation samples for:\n  - manpage\n  - user guide\n  - design doc\n  - doxygen output\n  - licenses\n- Uses [Sphinx](https://www.sphinx-doc.org/) with\n  [read-the-docs](https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html)\n  theme\n- [Doxygen](https://www.doxygen.nl/) for internal API\n- [PlantUML](https://plantuml.com/) to auto build diagrams\n- Makefile auto-generates PlantUML files into PNG files\n- Create or modify PlantUML files in `docs/src/images/src`\n- Suffix for PlantUML files must be `.puml`\n- Place or find auto created `.png`'s in `docs/src/images/pub`\n- Recommend creating diagrams with [Drawio](https://www.drawio.com/) and\n  maintain drawio source files in `docs/src/images/src`\n- Export drawio diagram as a PNG into `docs/src/images/pub`\n\n### Building the Docs\n\nFrom top level folder, invoke:\n\n```bash\nmake docs\nfirefox _build/site/index.html\n```\n\n### Pubishing the Docs\n\nWhen a release build is triggered, docs are built in the normal\n_build/site location and then copied to the `docs/site` folder so it can\nbe checked in to Git.  After a successful build, the `deploy-gh-pages`\nworkflow runs and publishes the documentation to GH pages.\n\nYou may need to configure GitHub pages in your repository. Not sure if\nthe GitHub pages settings come across from the template repo. To\nconfigure it, visit your \u003cGitHub repo\u003e/Settings-\u003ePages-\u003eGitHub\nPages. Ensure the `Build and deployment` section, under\n`Source` is selected for `GitHub Actions`.\n\n### Doxygen Setup\n\nDoxygen config file is setup to treat warnings as errors. This is easy\nto maintain on new projects, but this setting might be too strict for\nsome projects with already existing code. Change the\n`docs/src/doxygen/Doxyfile` setting from `WARN_AS_ERROR =\nFAIL_ON_WARNINGS` to `WARN_AS_ERROR = NO`.\n\nNot every single function or class is documented in doxygen style, nor\nshould they be.  Only those functions and classes that are meant to be\npublic need doxygen comments, because you want these to appear in the\npublished API. Private functions should still be documented, in general\nat your discretion, but do not need doxygen style comments.\n\n### Spell Checking Docs\n\n* Spell checking can be performed against a given file or a tree of files\n* Spell checking is invoked via Makefile target\n* Spell checking can be run in interactive or batch mode\n* Interactive mode lets you fix spelling in-place, file by file\n* Underlying (containerized) tool is [hunspell](https://linux.die.net/man/1/hunspell)\n\nMakefile targets for spelling:\n\n    spelling-clean    - Deletes spelling artifacts\n    spelling-help     - Displays help for spelling usage\n    spelling-it       - Spell checks all docs in interactive mode\n    spelling          - Spell checks all docs in batch mode\n    \u003cfilepath\u003e.bspell - Spell checks given file in batch mode\n    \u003cfilepath\u003e.ispell - Spell checks given file interactively\n\nFor full details invoke:\n\n``` bash\nmake spelling-help\n```\n\n### GitHub Workflows\n\nFour workflows manage this repo.\n\n1. build.yml - builds on any push\n2. release.yml - manually triggered when a release is desired\n3. shared-build.yml - performs both build and release activities\n4. deploy-gh-pages.yml - updates GitHub pages after a release\n\nWorkflows support developer controls to skip various parts\nof the build as desired.\n\n* Just add `[skip-\u003ckeyword\u003e]` somewhere in your commit message\n* See file `.github/workflows/shared-build.yml` for keywords\n\n## GitHub Workflows\n\n* Workflow for \"CI build\" - triggers upon merge to main\n* Workflow for \"Branch build\" - triggers upon checkin to branch\n* Branch build supports developer controls for skipping various parts\n\n## Containerized Tools\n\n- Uses containers for build tools (compiler, auto-docs, etc)\n- Supports Docker or Podman, prefers Podman over Docker if found\n- Containers mount local host workspace, no copying into container\n- GCC container is auto-started once and remains active\n- Re-compiles start immediately, no re-loading of GCC container\n- Same containers and tools on desktop and in CI pipelines\n- Pipelines invoke same make targets as developer does on desktop\n- Convenient Makefile targets abstract away container commands\n- The Build container uses\n  [docker.io/library/gcc](https://hub.docker.com/_/gcc) as its base\n  image which is a Debian distro, therefore executables you create are\n  for Debian Linux. If you want to build for a different distro then you\n  will want to [switch](#switching-build-container) out the Build\n  container with your own.\n- [Automated login](#container-registry-login) to container registries\n- Supports multiple container registries simultaneously\n\n**Why Containers**\n\n- *Avoids complex tool* management on host, avoids tool version pollution\n- *Consistent predictable* identical environment and workflow on both\n  host and pipeline/runner machines\n- *Avoids dependency issues* and version conflicts on the host and\n  pipeline/runner machines\n- *Reproducible builds* the set of containers used in a build captures\n  the entire environment as coherent tool set\n- *Prevents conflicts* between host and runners that might use different\n  tools and/or libraries for other activities\n\n### The Build Container \n\nThe build container houses executables for the compiler, CMake, and\nConan along with additional utilities.\n\nC++ Bootstrap provides a build container already setup for gcc14, C++20,\nCMake and Conan 2.0 -\n`ghcr.io/kingsolomon1954/containers/gcc14-tools:14.2.0`.  The makefile\nhas targets to build, push and pull the build container.\n\n``` bash\nmake help\n# filtered output\ncntr-build-gcc14-tools - Creates gcc14-tools image\ncntr-pull-gcc14-tools  - Pulls   gcc14-tools from ghcr.io\ncntr-push-gcc14-tools  - Pushes  gcc14-tools to ghcr.io\n```\n\nSee the docker file here:\n`tools/containers/spec-files/dockerfile-gcc14-tools`.\n\nThe build container, if it is not already running, is automatically\nstarted upon issuing any `make` target that involves compiling or\nlinking.  The build container runs in detached mode and hangs around for\nfurther future commands which execute immediately since the container is\nalready running. The makefile framework arranges commands to be issued\nto the build container using docker/podman `exec` command. The build\ncontainer is special in that it hangs around. Other containers, such as\nthose used for building documentation, start and exit after running\ntheir commands.\n\nThe strategy used with the build container is to mount your local\nworkspace. The compiler operates against your local workspace files\nwithout any copying.  You are thus free to use any editors/IDE,\nGit tools, etc., on your host computer as normal.\n\nBe aware that the Conan registry and Conan library cache live on the\nbuild container, not on your workspace. If the container is removed and\nrestarted then the Conan setup will be applied again and libraries will\nbe retrieved again.  This is purposely setup in this fashion (using the\ncontainer to hold the Conan cache) so that the same build container\ninstance, and thus all the Conan libraries, can be shared across\ndifferent repositories, resulting in significant efficiencies in\nmulti-repo projects, even though not much benefit for this single repo\nC++ Bootstrap project.\n\n### Handy Aliases for Build Container\n\nHere's several handy bash aliases that make working with the Build\nContainer easier. These are meant to be invoked while you're\nsitting in the top project folder on your host.\n\n```bash\nalias bd=\"podman exec -w /work/\\$(basename \\$(pwd))/_build/debug gcc14-tools\"\nalias bp=\"podman exec -w /work/\\$(basename \\$(pwd))/_build/prod gcc14-tools\"\nalias bt=\"podman exec -w /work/\\$(basename \\$(pwd)) gcc14-tools\"\nalias bbash='echo '\\''Use ctrl-p ctrl-q to quit'\\''; podman exec -it -w /work/$(basename $(pwd)) gcc14-tools bash'\n```\n\nMnemonically they can be interpreted as:\n\n- `bd` - run a command in the container from the_**b**uild/**d**ebug folder\n- `bp` - run a command in the container from the_**b**uild/**p**rod folder\n- `bt` - run a command in the **b**uild container from the **t**op folder\n- `bbash` - **bash** into to the **b**uild container at the shell prompt\n\nThese aliases are also available in a script. You will want to change\nthe value of _CPP_BOOTSTRAP_HOME in there first to agree with your\nenvironment.\n\n```bash\nsource tools/scripts/devenv.bash\n\n```\n\n### Container Registry Login\n\nSupports automated and manual login into container registries.\n\nEach container image can come from a different registry.  The registry\nthat C++ Bootstrap uses for a given container image is specified in the\n`tools/submakes/container-names-\u003ctool\u003e.mak`. Each containerized tool has\nits own container-names file.\n\nCurrently supports:\n\n* localhost\n* docker.io\n* ghcr.io\n* artifactory.io\n\nLogin credentials are read from the following locations on your host\nin the order shown:\n\n1. environment variables\n2. from files\n3. otherwise command line prompt\n\nReads credentials (personal access token(PAT) or password and\nuser name) from these environment variables if found:\n\n- reads env variable `\u003cREGISTRY\u003e_PAT`      (\".\" turned into underscore)\n- reads env variable `\u003cREGISTRY\u003e_USERNAME`\n\nFor example, if the container registry is `docker.io` then looks\nfor these environment variables:\n\n``` bash\n  DOCKER_IO_PAT         # personal access token / password\n  DOCKER_IO_USERNAME    # login user name for this registry\n```\n\nReads credentials (personal access token(PAT) or password and\nuser name) from these files if found:\n\n- reads access token file: `$HOME/.ssh/\u003cREGISTRY\u003e-token`\n- reads username file: `$HOME/.ssh/\u003cREGISTRY\u003e-username`\n\nFor example, if container registry is `docker.io` then looks\nfor these files:\n\n``` bash\n  $HOME/.ssh/docker.io-token     # personal access token / password\n  $HOME/.ssh/docker.io-username  # login user name for this registry\n```\n\nThese files should have just a single line each. For example:\n``` bash\n\u003e cat $HOME/.ssh/docker.io-token\ndhub_675b9Jam99721\n\u003e cat $HOME/.ssh/docker.io-username\nElvis\n```\n\n- if no env var or file, then prompts for PAT/password\n- if no env var or file, then prompts for username\n\n## Conan Setup\n\n- Setup as a consumer of Conan libraries, not a producer\n- Conan library cache is held on the build container, not the host machine\n- Automated Conan registry login scheme, supports multiple registries\n- Uses Conan lockfiles for locking down library versions for stable\n  repeatable builds\n- Makefile provides convenient commands to manipulate Conan on the container\n\n### Conan Auto-Registry Setup\n\nConan 2.0 supports multiple Conan registries. C++ Bootstrap comes\nprepared with two Conan Registry files already filled out.\n\n* `tools/conan/registry-conancenter.properties`\n* `tools/conan/registry-aws-arty.properties`\n\nThe first one is a real registry. conancenter exists. The second\none is a made up registry for the purpose of demonstration.\n\nC++ Bootstrap populates Conan registries into Conan just once, at build\ninitialization time, before any library retrieval is attempted.  And it\nre-populates these later if/when a new container is started, or if a\nregistry file changes.\n\nTo add or remove registries, just add or delete a file having the\nfollowing naming pattern:\n\n    tools/conan/registry-*.properties\n\nProperties found in these files are then used to setup each registry in\nConan. The parsing is not sophisticated or flexible, uses simple greps,\nso please adhere closely to the layout in the files.\n\nA Conan registry file looks like this:\n\n``` bash\n\u003e cat tools/conan/registry-aws-arty.properties\nname: aws-arty\nurl: https://aws.artifactory.io\nlogin: no\nenable: yes\npublish: yes\n\n```\n\n**name:** \\\u003cregistry\\\u003e the name you give to this Conan registry. Name is\none word. No quotes around it. Must be separated from the \":\" with a\nspace. Best to avoid dashes and periods in the name, although these will\nbe turned into an underscore for env-var names.\n\n**url:** \\\u003curl\\\u003e the registry server. url is one word. No quotes around\nit. Must be separated from the \":\" with a space.\n\n**login:** [yes|no] whether to perform automated login. See next section\nfor more details. One word. No quotes around it. Must be separated from\nthe \":\" with a space.\n\n**enable:** [yes|no] whether to use or hide this registry. One word. No\nquotes around it. Must be separated from the \":\" with a space. This is\nbuiltin Conan feature, not a C++ Bootstrap addition.\n\n**publish:** [yes|no] identify this registry as the one registry to use\nfor publishing your own Conan library packages. One word. No quotes\naround it. Must be separated from the \":\" with a space. Only one\nregistry can be be selected for publishing. If multiple property files\nindicate \"yes\", C++ Bootstrap will silently accept the first one it\nfinds. It is not an error if no registry is identified for publishing as\nwould be case if your project is a Conan consumer-only project.\n\n### Conan Auto-Login\n\nA registry can be configured in Conan with or without having Conan\nestablish a login to it. If your project is a Conan library consumer,\nthen generally you don't need a login. conancenter works this way. But\nsome registries require a login even for consumer-only operations.\n\nThe two registry property files that come with C++ Bootstrap currently\nspecify `login: no`. If a registry requires a login, change the login\nattribute to `login: yes`.\n\nC++ Bootstrap supports automated as well as manual login.\n\nFor automation, login credentials are read from the following locations\nin the given order, keying off of the name of the registry in\nthe property file (i.e., `name: \u003cregistry\u003e`).\n\n  1. from environment variables\n  2. from files\n  3. from command line prompt\n\n#### From Environment Variables\n\nReads credentials (personal access token(PAT) or password and\nuser name) from these environment variables if found:\n\n    \u003cREGISTRY\u003e_USERNAME\n    \u003cREGISTRY\u003e_PAT      (\"-\" turned into underscore)\n\nFor example, if the Conan registry is `aws-arty` then looks\nfor these environment variables:\n\n    AWS_ARTY_USERNAME    # login user name for this registry\n    AWS_ARTY_PAT         # personal access token / password\n\n#### From Files\n\nReads credentials (personal access token(PAT) or password and\nuser name) from files if found:\n\n    ~/.ssh/\u003cREGISTRY\u003e-username\n    ~/.ssh/\u003cREGISTRY\u003e-token\n\nFor example, if container registry is `aws-arty` then looks\nfor these files:\n\n    $HOME/.ssh/aws-arty-username  # login user name for this registry\n    $HOME/.ssh/aws-arty-token     # personal access token / password\n\nThese files have just a single line each. For example:\n\n``` bash\n\u003e cat $HOME/.ssh/aws-arty-username\nElvisTheDeveloper\n\u003e cat $HOME/.ssh/aws-arty-token\naws_regy_675b9Jam99721\n```\n\n#### From Command Line Prompt\n\nif no env-var or file, then prompts for PAT/password\u003cbr\u003e\nif no env-var or file, then prompts for username\n\n### Conan Library Publishing\n\nTBS\n\n## Static Code Analysis\n\nStatic code analysis can be performed against all source code in the\nrepository or against a single file. Built-in support for error\nsuppression-list. Underlying tool is a containerized `cppcheck`.\n\nThe following makefile targets are available:\n\n    static-analysis       - Runs C++ static analysis against repo\n    static-analysis-clean - Deletes C++ static analysis artifacts\n    static-analysis-help  - Displays help for C++ static analysis\n    \u003cfilepath\u003e.sta        - Runs C++ static analysis on given file\n\nFind results in `_build/static-analysis/report/index.html`.\n\n``` bash\nmake static-analysis\nfirefox _build/static-analysis/report/index.html\n```\n\nThe static analysis report is included and published as part of the site\ndocumentation. A newer static analysis report replaces a previous one\nprovided the newer static analysis report is available at the time `make\ndocs` is invoked. If no static analysis report is available at that\ntime, then the last published static analysis report remains.\n\n## Code Coverage\n\nTo get a code coverage report, invoke the following makefile\ntarget.\n\n``` bash\nmake code-coverage\nfirefox _build/debug/coverage/index.html\n```\n\nThis target rebuilds the debug tree with flags enabling coverage\nand profiling, then invokes the CMake `coverage` target which\ninvokes unit tests along with `gcov`. Find the report in the\n`_build/debug/coverage` folder.\n\nNote that normal debug builds do not enable coverage / profiling\nflags. These flags slow down compiles dramatically. Therefore this\nseparate makefile target is available for when you want focus on this\narea.\n\nThe code coverage report is included and published as part of the site\ndocumentation. A newer code coverage report replaces a previous one\nprovided the newer coverage report is available at the time `make docs`\nis invoked. If no coverage report is available at that time, then the\nlast published code coverage report remains.\n\n## Getting Started\n\n### 1. Prerequisites\n\n* Host machine: Install docker/podman\n* Host machine: Install standard linux utilities, bash, etc\n\n### 2. Retrieve C++ Starter Project\n\nGrab the repo as a\n[template](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template).\n\n### 3. First invocation\n\nSee if your host environment is suitable enough for `make help`.\n\n```bash\nmake help\n```\n\n### 4. Compile, Link, Test and Run\n\n```bash\nmake\nmake unit-test\nbd bin/RedFlame\n```\n\n## 5. Automate Registry Logins\n\nSetup Container and Conan login credentials in `~/.ssh`. See\n[Container Registry Login](#container-registry-login) and\n[Conan Auto-Login](#conan-auto-login).\n\n## 6. Customize\n\nCustomize the project to be your own.\n\n## Additional Activities\n\n### Switching Build Container\n\nAssuming you want to use your own locally built build container,\nmodify file `tools/submakes/container-names-gcc14.mak` as follows:\n\nChange:\n\n    CNTR_GCC_14_TOOLS_REPO  := ghcr.io\n    CNTR_GCC_14_TOOLS_IMAGE := kingsolomon1954/containers/gcc14-tools\n\nTo:\n\n    CNTR_GCC_14_TOOLS_REPO  := localhost\n    CNTR_GCC_14_TOOLS_IMAGE := gcc14-tools\n\nIf you haven't already built your own build container image, you can\ninvoke the following makefile target. This target uses the docker\nspec file at `tools/containers/container-files/dockerfile-gcc14-tools`.\n\n```bash\nmake cntr-build-gcc14-tools\n```\n\nYou should now have a container image in your local registry. Looks\nsomething like this:\n\n    REPOSITORY             TAG      IMAGE ID      CREATED        SIZE\n    localhost/gcc14-tools  latest   ec7fcbd0727b  2 months ago   1.78 GB\n\n### Switching Sphinx Container\n\nAssuming you want to use your own locally built Sphinx container,\nmodify file `tools/submakes/container-names-sphinx.mak` as follows:\n\nChange:\n\n    CNTR_SPHINX_REPO  := ghcr.io\n    CNTR_SPHINX_IMAGE := kingsolomon1954/containers/sphinx\n\nTo:\n\n    CNTR_SPHINX_REPO  := localhost\n    CNTR_SPHINX_IMAGE := sphinx\n\nIf you haven't already built your own Sphinx container image, you can\ninvoke the following makefile target. This target uses the docker\nspec file at `tools/containers/container-files/dockerfile-sphinx`.\n\n```bash\nmake cntr-build-sphinx-tools\n```\n\nYou should now have a container image in your local registry. Looks\nsomething like this:\n\n    REPOSITORY             TAG      IMAGE ID      CREATED        SIZE\n    localhost/sphinx       7.3.7    cd0fbf8fe687  3 months ago   367 MB\n\n### Compiling a Single File\n\nAssuming you have the container [aliases](#handy-aliases-for-build-container)\ndefined above:\n\n```bash\nbd make -C main src/Properties.o\nbd make -C lib-codec src/CodecFast.o\n```\n\nThis invokes the CMake generated Makefile on the build container\nspecifying the file to compile. Note this works only after a\nbuild has taken place and thus CMake has already been configured.\n\n### Compiling a Specific Target\n\nOften it is preferable and more efficient to compile only the target\nunder change as opposed to invoking the entire build.\n\nAssuming you have the container [aliases](#handy-aliases-for-build-container)\ndefined above:\n\n```bash\nbd make help        # See the CMake targets\nbd make lib-gen     # Build just the lib-gen library target\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingsolomon1954%2Fcpp-bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkingsolomon1954%2Fcpp-bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingsolomon1954%2Fcpp-bootstrap/lists"}