From a6c6183cb44ac7122afe391edac4d567eced0e7e Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Fri, 15 Dec 2023 14:10:49 -0500 Subject: [PATCH 1/2] README.md: ex13: + install step --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/README.md b/README.md index a0b5f48..d4e261a 100644 --- a/README.md +++ b/README.md @@ -3705,3 +3705,55 @@ Test project /home/roland/proj/cmake-examples/build Total Test time (real) = 0.05 sec ``` + +Install: +``` +$ cmake --install build +-- Install configuration: "" +-- Installing: /home/roland/scratch/include/compression +-- Installing: /home/roland/scratch/include/compression/tostr.hpp +-- Installing: /home/roland/scratch/include/compression/compression.hpp +-- Installing: /home/roland/scratch/include/compression/buffered_deflate_zstream.hpp +-- Installing: /home/roland/scratch/include/compression/base_zstream.hpp +-- Installing: /home/roland/scratch/include/compression/buffered_inflate_zstream.hpp +-- Installing: /home/roland/scratch/include/compression/inflate_zstream.hpp +-- Installing: /home/roland/scratch/include/compression/buffer.hpp +-- Installing: /home/roland/scratch/include/compression/deflate_zstream.hpp +-- Installing: /home/roland/scratch/include/compression/span.hpp +-- Installing: /home/roland/scratch/lib/libcompression.so.2 +-- Installing: /home/roland/scratch/lib/libcompression.so.2.3 +-- Set runtime path of "/home/roland/scratch/lib/libcompression.so.2" to "/home/roland/scratch/lib" +-- Installing: /home/roland/scratch/lib/libcompression.so +-- Installing: /home/roland/scratch/include/zstream +-- Installing: /home/roland/scratch/include/zstream/zstream.hpp +-- Installing: /home/roland/scratch/include/zstream/zstreambuf.hpp +-- Installing: /home/roland/scratch/bin/hello +-- Set runtime path of "/home/roland/scratch/bin/hello" to "/home/roland/scratch/lib" +-- Installing: /home/roland/scratch/bin/myzip +-- Set runtime path of "/home/roland/scratch/bin/myzip" to "/home/roland/scratch/lib" +$ tree ~/scratch +/home/roland/scratch +├── bin +│   ├── hello +│   └── myzip +├── include +│   ├── compression +│   │   ├── base_zstream.hpp +│   │   ├── buffer.hpp +│   │   ├── buffered_deflate_zstream.hpp +│   │   ├── buffered_inflate_zstream.hpp +│   │   ├── compression.hpp +│   │   ├── deflate_zstream.hpp +│   │   ├── inflate_zstream.hpp +│   │   ├── span.hpp +│   │   └── tostr.hpp +│   └── zstream +│   ├── zstream.hpp +│   └── zstreambuf.hpp +└── lib + ├── libcompression.so -> libcompression.so.2.3 + ├── libcompression.so.2 + └── libcompression.so.2.3 -> libcompression.so.2 + +5 directories, 16 files +``` From aecf2620022ed1920957b823cb993349158ca48d Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Tue, 19 Dec 2023 15:47:41 -0500 Subject: [PATCH 2/2] README.md: + ex14: github CI workflow --- README.md | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 180 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d4e261a..9c8163d 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,12 @@ and to provide an opinionated (though possibly flawed) version of best practice 10. ex10: add c++ unit test + header-only library dep O3 (`catch2`) 11. ex11: add bash unit test (for `myzip`) 12. ex12: refactor: use inflate/deflate (streaming) api for non-native solution -13. ex13: example c++ header-only library A2 (`zstream`) with A2 -> A1 -> O2, monorepo style +13. ex13: example c++ header-only library A2 (`zstream`) with A2 -> A1 -> O2, monorepo-style +14. ex14: github CI example -* ex14: find_package() support -* ex15: add pybind11 library +* ex15: find_package() support +* ex16: add pybind11 library (pyzstream) +* ex17: add sphinx doc * c++ executable X + library A, A -> O, separable-style provide find_package() support - can build using X-subdir's cmake if A built+installed @@ -50,6 +52,8 @@ and to provide an opinionated (though possibly flawed) version of best practice * add performance benchmarks. * add code coverage. +- monorepo-style: artifacts using dependencies supplied from same repo and build tree + ## Preliminaries Each example gets its own dedicated git branch @@ -2768,6 +2772,7 @@ $ tree ~/scratch # Example 13 Provide inflating/deflating specialization of `std::streambuf`. +This requires generalizing build to handle a mixture of internal-to-repo and external-to-repo library dependencies ``` $ cd cmake-examples @@ -2776,6 +2781,7 @@ $ git checkout ex13 source tree: ``` +$ tree . ├── CMakeLists.txt ├── LICENSE @@ -3757,3 +3763,174 @@ $ tree ~/scratch 5 directories, 16 files ``` + +# Example 14 + +Provide github action support. +This will only work out-of-the-box for a project hosted on github; +that said, you can expect the mechanics we rely on here to translate to other CI platforms. + +``` +$ cd cmake-examples +$ git checkout ex14 +``` + +source tree: +``` +$ tree .github +.github +└── workflows + └── ex14.yml + +1 directory, 1 file +``` + +(otherwise source tree unchanged from previous example) +``` +$ tree +. +├── CMakeLists.txt +├── LICENSE +├── README.md +├── app +│   ├── hello +│   │   ├── CMakeLists.txt +│   │   └── hello.cpp +│   └── myzip +│   ├── CMakeLists.txt +│   ├── myzip.cpp +│   └── utest +│   ├── CMakeLists.txt +│   ├── myzip.utest +│   └── textfile +├── compile_commands.json -> build/compile_commands.json +├── compression +│   ├── CMakeLists.txt +│   ├── buffered_deflate_zstream.cpp +│   ├── buffered_inflate_zstream.cpp +│   ├── compression.cpp +│   ├── deflate_zstream.cpp +│   ├── include +│   │   └── compression +│   │   ├── base_zstream.hpp +│   │   ├── buffer.hpp +│   │   ├── buffered_deflate_zstream.hpp +│   │   ├── buffered_inflate_zstream.hpp +│   │   ├── compression.hpp +│   │   ├── deflate_zstream.hpp +│   │   ├── inflate_zstream.hpp +│   │   ├── span.hpp +│   │   └── tostr.hpp +│   ├── inflate_zstream.cpp +│   └── utest +│   ├── CMakeLists.txt +│   ├── compression.test.cpp +│   └── compression_utest_main.cpp +└── zstream + ├── CMakeLists.txt + ├── include + │   └── zstream + │   ├── zstream.hpp + │   └── zstreambuf.hpp + └── utest + ├── CMakeLists.txt + ├── text.cpp + ├── text.hpp + ├── zstream.test.cpp + ├── zstream_utest_main.cpp + └── zstreambuf.test.cpp + +12 directories, 38 files +``` + +Changes: +1. new directory `.github/workflows` +2. new file `.github/workflows/ex14.yml` + I believe any `.yml` file in `.github/workflows` will be included as a trigger for github actions. + +ex14.yml: +``` +# workflow for building cmake-examples +# using stock github runner (in practice some ubuntu release) +# + +name: cmake-examples builder + +on: + # trigger github-hosted rebuild when contents of branch 'ex14' changes + # (most project would use 'main' here; the progressive branch structure + # of cmake-examples makes that not viable, since the build we want to invoke + # doesn't exist in the 'main' branch) + # + push: + branches: [ "ex14" ] + pull_request: + branches: [ "ex14" ] + +env: + BUILD_TYPE: Release + +jobs: + ex14_build: + name: compile ex14 artifacts + run unit tests + runs-on: ubuntu-latest + + # ---------------------------------------------------------------- + # external dependencies + + steps: + - name: install catch2 + run: sudo apt-get install -y catch2 + + #- name: check package list + # run: apt-cache search boost + + - name: install boost program-options + run: sudo apt-get install -y libboost-program-options1.74-dev + + # ---------------------------------------------------------------- + # filesystem tree on runner + # + # ${{github.workspace}} + # +- repo + # | \- cmake-examples # source tree + # \- build + # \- cmake_examples # build location + # + + - name: checkout cmake-examples source + # see https://github.com/actions/checkout for latest + + uses: actions/checkout@v3 + with: + ref: ex14 + path: repo/cmake-examples + + - name: prepare build directory + run: mkdir -p build/cmake-examples + + - name: configure cmake-examples + run: cmake -B ${{github.workspace}}/build/cmake-examples -DCMAKE_INSTALL_PREFIX=${{github.workspace}}/local repo/cmake-examples + + - name: build cmake-examples + run: cmake --build ${{github.workspace}}/build/cmake-examples --config ${{env.BUILD_TYPE}} + + - name: test cmake-examples + run: (cd ${{github.workspace}}/build/cmake-examples && ctest) + + - name: install cmake-examples + run: cmake --install ${{github.workspace}}/build/cmake-examples + +``` + +Remarks: +1. You can review github actions activity at this url: https://github.com/rconybea/cmake-examples/actions +2. Our CI workflow starts with a stock linux image (`ubuntu-latest`) provided by github. + We can and must install additional dependencies (`catch2`, `boost`) +3. Note that we don't get full control over the CI host environment here - for example we rely on + the boost version that comes with whichever ubuntu release github provides; + it's possible for CI to fail sometime if/when a non-backward-compatible change shows up in + latest ubuntu release. +4. We can achieve a fully-reproducible CI pipeline by containerizing. + See `.github/workflows/main.yml` in https://github.com/rconybea/xo-nix3 for github CI workflow using a custom docker container. + See https://github.com/rconybea/docker-xo-builder for construction of the docker container