From 8060ef76a0bb778f3d2eac1f7a4270d56f8bca58 Mon Sep 17 00:00:00 2001 From: Darius Neatu Date: Thu, 25 Jul 2024 15:41:57 +0300 Subject: [PATCH] Apply the latest Beman Standard --- .ci/docker/rockylinux.Dockerfile | 21 +- .ci/docker/ubuntu.Dockerfile | 19 +- .github/CODEOWNERS | 4 + .github/workflows/{cxx.yml => ci_tests.yml} | 20 +- .gitignore | 8 + CMakeLists.txt | 28 +- LICENSE | 278 ++++++++++++++++++++ LICENSE.txt | 21 -- README.md | 108 ++++++-- examples/CMakeLists.txt | 23 ++ examples/sample_usage.cpp | 9 + include/Beman/Example/example.hpp | 9 + src/Beman/Example/CMakeLists.txt | 52 ++++ src/Beman/Example/example.cpp | 9 + src/Beman/Example/tests/CMakeLists.txt | 18 ++ src/Beman/Example/tests/example.t.cpp | 11 + src/example/CMakeLists.txt | 39 --- src/example/example.cpp | 2 - src/example/example.hpp | 2 - test/example/CMakeLists.txt | 8 - test/example/example.test.cpp | 5 - 21 files changed, 570 insertions(+), 124 deletions(-) create mode 100644 .github/CODEOWNERS rename .github/workflows/{cxx.yml => ci_tests.yml} (71%) create mode 100644 .gitignore create mode 100644 LICENSE delete mode 100644 LICENSE.txt create mode 100644 examples/CMakeLists.txt create mode 100644 examples/sample_usage.cpp create mode 100644 include/Beman/Example/example.hpp create mode 100644 src/Beman/Example/CMakeLists.txt create mode 100644 src/Beman/Example/example.cpp create mode 100644 src/Beman/Example/tests/CMakeLists.txt create mode 100644 src/Beman/Example/tests/example.t.cpp delete mode 100644 src/example/CMakeLists.txt delete mode 100644 src/example/example.cpp delete mode 100644 src/example/example.hpp delete mode 100644 test/example/CMakeLists.txt delete mode 100644 test/example/example.test.cpp diff --git a/.ci/docker/rockylinux.Dockerfile b/.ci/docker/rockylinux.Dockerfile index 9821de2..aa0121f 100644 --- a/.ci/docker/rockylinux.Dockerfile +++ b/.ci/docker/rockylinux.Dockerfile @@ -1,29 +1,34 @@ +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + FROM rockylinux:9 -# Enable EPEL +# Enable EPEL. RUN dnf update -y RUN dnf install -y 'dnf-command(config-manager)' RUN dnf config-manager --set-enabled crb -y RUN dnf install epel-release -y -# Install dependencies +# Install dependencies. RUN dnf install -y \ clang \ g++ \ ninja-build \ - cmake + cmake \ + git RUN dnf clean all -# Copy code +# Copy code. WORKDIR /workarea COPY ./ ./ +# Set build arguments. ARG cc=gcc ARG cxx=g++ ARG cmake_args= +# Build. ENV CC="$cc" CXX="$cxx" CMAKE_GENERATOR="Ninja" CMAKE_EXPORT_COMPILE_COMMANDS=on -RUN cmake -B build -S . "$cmake_args" && \ - cmake --build build --verbose && \ - DESTDIR=build/staging cmake --install build --prefix /opt/example --component libexample-dev && \ - find build/staging -type f +RUN cmake -B build -S . "$cmake_args" +RUN cmake --build build --verbose +RUN DESTDIR=build/staging cmake --install build --prefix /opt/beman/example --component libbeman_example-dev +RUN find build/staging -type f diff --git a/.ci/docker/ubuntu.Dockerfile b/.ci/docker/ubuntu.Dockerfile index fbfe4ed..9f7a591 100644 --- a/.ci/docker/ubuntu.Dockerfile +++ b/.ci/docker/ubuntu.Dockerfile @@ -1,19 +1,23 @@ -# Using a non-LTS Ubuntu, just until CMake 3.23 is available on Ubuntu 24.04 +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +# Using a non-LTS Ubuntu, just until CMake 3.23 is available on Ubuntu 24.04. FROM ubuntu:23.10 -# Install dependencies +# Install dependencies, RUN apt-get update RUN apt-get install -y \ clang \ clang-tidy \ g++ \ ninja-build \ - cmake + cmake \ + git RUN apt-get clean WORKDIR /workarea COPY ./ ./ +# Set build arguments. ARG cc=gcc ARG cxx=g++ ARG cmake_args= @@ -21,8 +25,9 @@ ARG cmake_args= # Workaround Ubuntu broken ASan RUN sysctl vm.mmap_rnd_bits=28 +# Build. ENV CC="$cc" CXX="$cxx" CMAKE_GENERATOR="Ninja" CMAKE_EXPORT_COMPILE_COMMANDS=on -RUN cmake -B build -S . "$cmake_args" && \ - cmake --build build --verbose && \ - DESTDIR=build/staging cmake --install build --prefix /opt/example --component libexample-dev && \ - find build/staging -type f +RUN cmake -B build -S . "$cmake_args" +RUN cmake --build build --verbose +RUN DESTDIR=build/staging cmake --install build --prefix /opt/beman/example --component libbeman_example-dev +RUN find build/staging -type f diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..fbbea91 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,4 @@ +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +# Codeowners for reviews on PRs + +* @bbrown105 @dustingooding @JamesAdkison @neatudarius diff --git a/.github/workflows/cxx.yml b/.github/workflows/ci_tests.yml similarity index 71% rename from .github/workflows/cxx.yml rename to .github/workflows/ci_tests.yml index 2ac2e49..f1c7378 100644 --- a/.github/workflows/cxx.yml +++ b/.github/workflows/ci_tests.yml @@ -1,7 +1,6 @@ -# Copyright © 2024 Bret Brown -# SPDX-License-Identifier: MIT +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -name: Test +name: CI Test on: push: @@ -30,14 +29,23 @@ jobs: - { id: ubuntu-gcc-aubsan, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_FLAGS=-fsanitize=address -fsanitize=undefined"} - { id: ubuntu-gcc-tsan, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_FLAGS=-fsanitize=thread"} - { id: ubuntu-gcc-static, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: ""} + - { id: ubuntu-gcc-dynamic, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DBUILD_SHARED_LIBS=on"} + - { id: ubuntu-clang-static, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: ""} + - { id: ubuntu-clang-dynamic, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DBUILD_SHARED_LIBS=on"} - { id: ubuntu-gcc-static-cxx98, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_STANDARD=98 -DCMAKE_CXX_STANDARD_REQUIRED=on"} - { id: ubuntu-gcc-static-cxx11, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_STANDARD=11 -DCMAKE_CXX_STANDARD_REQUIRED=on"} - { id: ubuntu-gcc-static-cxx14, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_STANDARD=14 -DCMAKE_CXX_STANDARD_REQUIRED=on"} - { id: ubuntu-gcc-static-cxx17, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_STANDARD=17 -DCMAKE_CXX_STANDARD_REQUIRED=on"} - { id: ubuntu-gcc-static-cxx20, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_STANDARD=20 -DCMAKE_CXX_STANDARD_REQUIRED=on"} - - { id: ubuntu-gcc-dynamic, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DBUILD_SHARED_LIBS=on"} - - { id: ubuntu-clang-static, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: ""} - - { id: ubuntu-clang-dynamic, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DBUILD_SHARED_LIBS=on"} + - { id: ubuntu-gcc-static-cxx23, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_STANDARD=23 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-gcc-static-cxx26, platform: ubuntu, cc: gcc, cpp: g++, cmake_args: "-DCMAKE_CXX_STANDARD=26 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-clang-static-cxx98, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DCMAKE_CXX_STANDARD=98 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-clang-static-cxx11, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DCMAKE_CXX_STANDARD=11 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-clang-static-cxx14, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DCMAKE_CXX_STANDARD=14 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-clang-static-cxx17, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DCMAKE_CXX_STANDARD=17 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-clang-static-cxx20, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DCMAKE_CXX_STANDARD=20 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-clang-static-cxx23, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DCMAKE_CXX_STANDARD=23 -DCMAKE_CXX_STANDARD_REQUIRED=on"} + - { id: ubuntu-clang-static-cxx26, platform: ubuntu, cc: clang, cpp: clang++, cmake_args: "-DCMAKE_CXX_STANDARD=26 -DCMAKE_CXX_STANDARD_REQUIRED=on"} # Disabling Rocky until it catches up on CMake versions or a way to sideload newer version of CMake # is identified. # - { id: rockylinux-gcc-static, platform: rockylinux, cc: gcc, cpp: g++, cmake_args: ""} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..25fc4b4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +cmake.bld +compile_commands.json +/.build/ +/build/ +/.cache/ +*.pyg +.update-submodules +.vscode/ diff --git a/CMakeLists.txt b/CMakeLists.txt index 9e06dca..99d5764 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,16 +1,32 @@ -# Copyright © 2024 Bret Brown -# SPDX-License-Identifier: MIT +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception cmake_minimum_required(VERSION 3.23) -project(example + +project(beman_example VERSION 1.0.0 DESCRIPTION "An example Beman library" LANGUAGES CXX ) -include(CTest) -add_subdirectory(src/example) +# Include the CTest module. +include(CTest) +# Build the tests only if enabled via the CLI flag: BUILD_TESTING. if (BUILD_TESTING) - add_subdirectory(test/example) + enable_testing() + + # Fetch GoogleTest + include(FetchContent) + FetchContent_Declare( + googletest + GIT_REPOSITORY https://github.com/google/googletest.git + GIT_TAG f8d7d77c06936315286eb55f8de22cd23c188571 # release-1.14.0 + ) + FetchContent_MakeAvailable(googletest) endif () + +# Build the library. +add_subdirectory(src/Beman/Example) + +# Build the examples. +add_subdirectory(examples) diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5715176 --- /dev/null +++ b/LICENSE @@ -0,0 +1,278 @@ +============================================================================== +The LLVM Project is under the Apache License v2.0 with LLVM Exceptions: +============================================================================== + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + +---- LLVM Exceptions to the Apache 2.0 License ---- + +As an exception, if, as a result of your compiling your source code, portions +of this Software are embedded into an Object form of such source code, you +may redistribute such embedded portions in such Object form without complying +with the conditions of Sections 4(a), 4(b) and 4(d) of the License. + +In addition, if you combine or link compiled forms of this Software with +software that is licensed under the GPLv2 ("Combined Software") and if a +court of competent jurisdiction determines that the patent provision (Section +3), the indemnity provision (Section 9) or other Section of the License +conflicts with the conditions of the GPLv2, you may retroactively and +prospectively choose to deem waived or otherwise exclude such Section(s) of +the License, but only in their entirety and only with respect to the Combined +Software. + +============================================================================== +Software from third parties included in the LLVM Project: +============================================================================== +The LLVM Project contains third party software which is under different license +terms. All such code will be identified clearly using at least one of two +mechanisms: +1) It will be in a separate directory tree with its own `LICENSE.txt` or + `LICENSE` file at the top containing the specific license and restrictions + which apply to that software, or +2) It will contain specific license and restriction terms at the top of every + file. + +============================================================================== +Legacy LLVM License (https://llvm.org/docs/DeveloperPolicy.html#legacy): +============================================================================== +University of Illinois/NCSA +Open Source License + +Copyright (c) 2003-2019 University of Illinois at Urbana-Champaign. +All rights reserved. + +Developed by: + + LLVM Team + + University of Illinois at Urbana-Champaign + + http://llvm.org + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal with +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimers. + + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimers in the + documentation and/or other materials provided with the distribution. + + * Neither the names of the LLVM Team, University of Illinois at + Urbana-Champaign, nor the names of its contributors may be used to + endorse or promote products derived from this Software without specific + prior written permission. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE +SOFTWARE. diff --git a/LICENSE.txt b/LICENSE.txt deleted file mode 100644 index 3fa2497..0000000 --- a/LICENSE.txt +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2024 Bret Brown - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/README.md b/README.md index 69fcafa..6b587b1 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,51 @@ -# example +# Beman.Example: A Beman Library Example -## About +![CI Tests](https://github.com/beman-project/Example/actions/workflows/ci_tests.yml/badge.svg) -`example` is an example Beman library. +`Beman.Example` is an example Beman library. `Beman.Example` is useful for nothing, though it might contain value as an experiment in modern and minimal C++ project structure. Please check [The Beman Standard](https://github.com/beman-project/beman/blob/main/docs/beman-standard.md). -`example` is useful for nothing, though it might contain value as an experiment in modern and minimal C++ project structure. +Implements: N/A for `Beman.Example`. +## License + +Source and docs are licenced with Apache License v2.0 with LLVM Exceptions. Copy the contents and incorporate in your own work as you see fit. + +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception ## Building ### Dependencies -This project is mainly tested on Ubuntu 22.04, but it should be as portable as CMake is. +This project is mainly tested on Ubuntu `22.04` and `24.04`, but it should be as portable as CMake is. -This project has zero C or C++ depenendencies. +This project has no C or C++ dependencies. -It does require two tools as build-time dependencies: +Build-time dependencies: -- `cmake` +- `cmake` - `ninja`, `make`, or another CMake-supported build system - CMake defaults to "Unix Makefiles" on POSIX systems +Example of installation on `Ubuntu 24.04`: + +```shell +# Install tools: +apt-get install -y cmake make ninja-build + +# Example of toolchains: +apt-get install \ + g++-14 gcc-14 gcc-13 g++-14 \ + clang-18 clang++-18 clang-17 clang++-17 +``` + ### Instructions +Full set of supported toolchains can be found in [.github/workflows/ci_test.yml](.github/workflows/ci_test.yml). + #### Basic Build This project strives to be as normal and simple a CMake project as possible. This build workflow in particular will work, producing a static `example` library, ready to package: @@ -37,9 +55,52 @@ cmake -B /some/build/dir -S . cmake --build /some/build/dir ctest --test-dir /some/build/dir \ --output-junit build/xunit/results.xml -DESTDIR=/some/staging/dir cmake --install /some/build/dir --component libexample-dev --prefix /opt/example +DESTDIR=/some/staging/dir cmake --install /some/build/dir --component libbeman_example-dev --prefix /opt/example ``` +
+ Build example + +```shell +# Configure example. +$ cmake -B .build -S . +-- The CXX compiler identification is GNU 13.2.0 +-- Detecting CXX compiler ABI info +-- Detecting CXX compiler ABI info - done +-- Check for working CXX compiler: /usr/bin/c++ - skipped +-- Detecting CXX compile features +-- Detecting CXX compile features - done +-- Configuring done (0.1s) +-- Generating done (0.0s) +-- Build files have been written to: /path/to/repo/.build + +# Build example. +$ cmake --build .build/ +[ 14%] Built target gtest +[ 28%] Built target gmock +[ 42%] Built target gmock_main +[ 57%] Built target gtest_main +[ 71%] Built target beman_example +[ 78%] Building CXX object src/Beman/Example/tests/CMakeFiles/example_gtest.dir/example.t.cpp.o +[ 85%] Linking CXX executable example_gtest +[ 85%] Built target example_gtest +[100%] Built target sample_usage + +# Run tests example. +$ ctest --test-dir .build +Internal ctest changing into directory: /path/to/repo/.build +Test project /path/to/repo/.build + Start 1: ExampleTest.call_identity +1/1 Test #1: ExampleTest.call_identity ........ Passed 0.00 sec + +100% tests passed, 0 tests failed out of 1 + +# Run examples. +$ .build/examples/sample_usage +2024 +``` +
+ If all of those steps complete successfully, you should see the library installed in your staging directory. An example command: @@ -63,6 +124,14 @@ You will see files like so: └── libexample.a ``` +#### Disable Tests Build + +To build this project with skiped tests and its dependencies, simply use `BUILD_TESTING=OFF` [as documented in upstream CMake documentation](https://cmake.org/cmake/help/latest/module/CTest.html: + +```shell +cmake -B /some/build/dir -S . -DBUILD_TESTING=OFF +``` + #### Manipulating Warnings To build this project with warnings enabled, simply use `CMAKE_CXX_FLAGS` [as documented in upstream CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html): @@ -106,33 +175,32 @@ Otherwise follow the Basic Build workflow as described above. ### From C++ -If you *really* want to use `example` from your project (why???), you can include `example.hxx` from your C++ source files +If you *really* want to use `Beman.Example` from your project (why???), you can include `Beman/Example/example.hpp` from your C++ source files ```cxx -#include +#include ``` -`example` supports C++98, C++03, C++11, C++14, C++17, C++20, and C++23. It has no known issues with C++26 or C++29, though there are no compilation toolchains available to test against in those build modes. +`Beman.Example` supports C++98, C++03, C++11, C++14, C++17, C++20, C+=23 and C++23. It has no known issues with C++29, though there are no compilation toolchains available to test against in those build modes. -Note that `example` is incidentally compatible with most C dialects, but that behavior is not regularly tested and should be considered unsupported. ### From CMake -For consumers using CMake, you will need to use the `example` CMake module to define the `example` CMake target: +For consumers using CMake, you will need to use the `beman_example` CMake module to define the `beman_example` CMake target: ```cmake -find_package(example REQUIRED) +find_package(beman_example REQUIRED) ``` -You will also need to add `example::example` to the link libraries of any libraries or executables that include `example.hxx` in their source or header file. +You will also need to add `beman::example` to the link libraries of any libraries or executables that include `example.hpp` in their source or header file. ```cmake -target_link_libraries(yourlib PUBLIC example::example) +target_link_libraries(yourlib PUBLIC beman::example) ``` ### From Other Build Systems -Build systems that support `pkg-config` by providing a `example.pc` file. Build systems that support interoperation via `pkg-config` should be able to detect `example` for you automatically. +Build systems that support `pkg-config` by providing a `beman_example.pc` file. Build systems that support interoperation via `pkg-config` should be able to detect `beman_example` for you automatically. ## Contributing diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt new file mode 100644 index 0000000..84fe3e3 --- /dev/null +++ b/examples/CMakeLists.txt @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +# List of all buildable examples. +set(EXAMPLES + sample_usage +) + +foreach(EXAMPLE ${EXAMPLES}) + # Add example executable. + add_executable(${EXAMPLE} "") + + # Add example source file. + target_sources(${EXAMPLE} PRIVATE ${EXAMPLE}.cpp) + + # Link example with the library. + target_link_libraries(${EXAMPLE} beman::example) + + # Install . + install( + TARGETS ${EXAMPLE} + EXPORT ${TARGETS_EXPORT_NAME} + DESTINATION ${CMAKE_INSTALL_BINDIR}) +endforeach() diff --git a/examples/sample_usage.cpp b/examples/sample_usage.cpp new file mode 100644 index 0000000..4f4e1ef --- /dev/null +++ b/examples/sample_usage.cpp @@ -0,0 +1,9 @@ +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +#include +#include + +int main(int, char*[]) { + std::cout << beman::example::identity(2024) << std::endl; + return 0; +} diff --git a/include/Beman/Example/example.hpp b/include/Beman/Example/example.hpp new file mode 100644 index 0000000..3a2289f --- /dev/null +++ b/include/Beman/Example/example.hpp @@ -0,0 +1,9 @@ +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +namespace beman { +namespace example { +// C++ example API (C++98-26): `api` <=> identity function. +int identity(int x); + +} // namespace example +} // namespace beman diff --git a/src/Beman/Example/CMakeLists.txt b/src/Beman/Example/CMakeLists.txt new file mode 100644 index 0000000..bbbabe9 --- /dev/null +++ b/src/Beman/Example/CMakeLists.txt @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +# Add the library. +add_library(beman_example STATIC "") +add_library(beman::example ALIAS beman_example) + +# Using the full project version because example does not provide a stable ABI +# between shared library versions +set_property(TARGET beman_example PROPERTY SOVERSION "${PROJECT_VERSION}") + +# Set the C++ sources. +target_sources(beman_example PRIVATE + example.cpp +) +target_include_directories( + beman_example + PUBLIC + $ + $ # /include/scratch +) +# target_sources(example PUBLIC +# FILE_SET HEADERS +# BASE_DIRS ../../../ +# FILES ../../../include/ +# ) + +# GNUInstallDirs provides default definitions for CMAKE_INSTALL_LIBDIR +# See: https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html +include(GNUInstallDirs) + +# Install the library. +install(TARGETS beman_example + EXPORT beman_example + ARCHIVE + COMPONENT libbeman_example-dev + FILE_SET HEADERS + COMPONENT libbeman_example-dev + LIBRARY + COMPONENT libbeman_example + NAMELINK_COMPONENT libbeman_example-dev +) +install(EXPORT beman_example + FILE beman_example-config.cmake + DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${TARGET_LIBRARY}" + COMPONENT libbeman_example-dev + NAMESPACE beman:: +) + +# Build the tests only if enabled via the CLI flag: BUILD_TESTING. +if (BUILD_TESTING) + add_subdirectory(tests) +endif () diff --git a/src/Beman/Example/example.cpp b/src/Beman/Example/example.cpp new file mode 100644 index 0000000..51c76d4 --- /dev/null +++ b/src/Beman/Example/example.cpp @@ -0,0 +1,9 @@ +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +#include + +namespace beman::example { + +int identity(int x) { return x; } + +} // namespace beman::example diff --git a/src/Beman/Example/tests/CMakeLists.txt b/src/Beman/Example/tests/CMakeLists.txt new file mode 100644 index 0000000..1d730d4 --- /dev/null +++ b/src/Beman/Example/tests/CMakeLists.txt @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +# Include the GoogleTest CMake module. +include(GoogleTest) + +# Add the test executable. +add_executable(beman_example_test) + +# Set the C++ sources. +target_sources(beman_example_test PRIVATE + example.t.cpp +) + +# Link the library. +target_link_libraries(beman_example_test PRIVATE beman::example GTest::gtest GTest::gtest_main) + +# Add the tests. +gtest_add_tests(beman_example_test "" AUTO) diff --git a/src/Beman/Example/tests/example.t.cpp b/src/Beman/Example/tests/example.t.cpp new file mode 100644 index 0000000..51dd2f0 --- /dev/null +++ b/src/Beman/Example/tests/example.t.cpp @@ -0,0 +1,11 @@ +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +#include + +#include + +TEST(ExampleTest, call_identity) { + for (int i = -100; i < 100; ++i) { + EXPECT_EQ(i, beman::example::identity(i)); + } +} diff --git a/src/example/CMakeLists.txt b/src/example/CMakeLists.txt deleted file mode 100644 index 1319831..0000000 --- a/src/example/CMakeLists.txt +++ /dev/null @@ -1,39 +0,0 @@ -# Copyright © 2024 Bret Brown -# SPDX-License-Identifier: MIT - -add_library(example) -add_library(example::example ALIAS example) - -# Using the full project version because example does not provide a stable ABI -# between shared library versions -set_property(TARGET example PROPERTY SOVERSION "${PROJECT_VERSION}") - -target_sources(example PRIVATE - example.cpp -) -target_sources(example PUBLIC - FILE_SET HEADERS - BASE_DIRS . - FILES example.hpp -) - -# GNUInstallDirs provides default definitions for CMAKE_INSTALL_LIBDIR -# See: https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html -include(GNUInstallDirs) - -install(TARGETS example - EXPORT example - ARCHIVE - COMPONENT libexample-dev - FILE_SET HEADERS - COMPONENT libexample-dev - LIBRARY - COMPONENT libexample - NAMELINK_COMPONENT libexample-dev -) -install(EXPORT example - FILE example-config.cmake - DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/example" - COMPONENT libexample-dev - NAMESPACE example:: -) diff --git a/src/example/example.cpp b/src/example/example.cpp deleted file mode 100644 index 1aff651..0000000 --- a/src/example/example.cpp +++ /dev/null @@ -1,2 +0,0 @@ -// Copyright © 2024 Bret Brown -// SPDX-License-Identifier: MIT diff --git a/src/example/example.hpp b/src/example/example.hpp deleted file mode 100644 index 1aff651..0000000 --- a/src/example/example.hpp +++ /dev/null @@ -1,2 +0,0 @@ -// Copyright © 2024 Bret Brown -// SPDX-License-Identifier: MIT diff --git a/test/example/CMakeLists.txt b/test/example/CMakeLists.txt deleted file mode 100644 index 9f0b3a4..0000000 --- a/test/example/CMakeLists.txt +++ /dev/null @@ -1,8 +0,0 @@ -add_executable(example.test) -target_sources(example.test PRIVATE example.test.cpp) -target_link_libraries(example.test PRIVATE example::example) - -add_test( - NAME example.test - COMMAND example.test -) diff --git a/test/example/example.test.cpp b/test/example/example.test.cpp deleted file mode 100644 index b5b8c08..0000000 --- a/test/example/example.test.cpp +++ /dev/null @@ -1,5 +0,0 @@ -#include - -int main(int, char*[]) { - return 0; -}