diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index aade3f0b..83f015bc 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -11,12 +11,13 @@ assignees: '' A clear and concise description of what the bug is. **Supporting Documentation** -If your issue is CAN behavior related, it may be helpful to have a CAN trace of your issue that clearly shows the undesirable behavior. Please attach one if you think it might help, or if requested. Try to capture address claiming in addition to the bad behavior if possible. We prefer files captured with `candump -l` or `.asc` ascii format log files. Binary Vector files `.blf` will not be accepted. +If your issue is CAN behavior related, it may be helpful to have a CAN trace of your issue that clearly shows the undesirable behavior. Please attach one if you think it might help, or if requested. Try to capture address claiming in addition to the bad behavior if possible. We prefer files captured with `candump -l` or `.asc` ascii format log files. Binary Vector files `.blf` will not be accepted. **Environment (please complete the following information):** - - OS: [e.g. Ubuntu 20.04] - - Compiler [e.g. GCC 9.4.0] - - CAN Driver [e.g. Socket CAN] + +- OS: [e.g. Ubuntu 20.04] +- Compiler [e.g. GCC 9.4.0] +- CAN Driver [e.g. Socket CAN] **Additional context** Add any other context about the problem here that you think might help us recreate or otherwise address your issue if applicable. diff --git a/CMakeLists.txt b/CMakeLists.txt index 9d52a678..5a9aa393 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,7 +11,8 @@ project( include(GNUInstallDirs) include(CMakePackageConfigHelpers) -# Make CTest available which adds the option BUILD_TESTING +# Make CTest available and the BUILD_TESTING option (OFF by default) +option(BUILD_TESTING "Set to ON to enable building of tests from top level" OFF) include(CTest) if(BUILD_TESTING AND NOT MSVC diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e45591e1..492c1f57 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,20 +10,20 @@ Our code style rules and PR reviews are based loosely on Autosar's `Guidelines f * Contributions must follow the style defined in our `.clang-format` and `.cmake-format` files. You can ensure you pass this check by running `find . -iname *.hpp -o -iname *.cpp | xargs clang-format -i` and `find . -name CMakeLists.txt | xargs cmake-format -i` at the root of the repo before submitting your PR. * Contributions should follow these additional style requirements, which will be checked in code reviews. - * Function names `snake_case` - * Variables `camelCase` - * Constant values `CAPITALIZED_SNAKE` - * Constants on the left in `==` and `!=` checks. Like this: `if (5 == value)` NOT `if (value == 5)`. This is to prevent accidentally omitting an `=` in the operator and creating a runtime bug. - * Copyright notice must be included in each file. - * `NULL` should not be used when `nullptr` can be used - * Explicit namespacing should be used for accessing namespaces outside of our namespace `isobus`, especially for the standard library `std::` - * No `using namespace` directives are allowed in header files - * Constructors with a single parameter shall be marked `explicit` - * Where possible, append `const` to functions that do not modify class member variables - * Where possible, declare variables as `constexpr` if their value can be determined at compile time - * Only those characters specified in the C++ Language Standard basic source character set shall be used in the source code except within the text of a wide string. - * In general, prefer C++ over C, though exceptions may be granted if needed - * This list of style items is not exhaustive, and some best practices such as include guards will also be checked in our PR reviews. + * Function names `snake_case` + * Variables `camelCase` + * Constant values `CAPITALIZED_SNAKE` + * Constants on the left in `==` and `!=` checks. Like this: `if (5 == value)` NOT `if (value == 5)`. This is to prevent accidentally omitting an `=` in the operator and creating a runtime bug. + * Copyright notice must be included in each file. + * `NULL` should not be used when `nullptr` can be used + * Explicit namespacing should be used for accessing namespaces outside of our namespace `isobus`, especially for the standard library `std::` + * No `using namespace` directives are allowed in header files + * Constructors with a single parameter shall be marked `explicit` + * Where possible, append `const` to functions that do not modify class member variables + * Where possible, declare variables as `constexpr` if their value can be determined at compile time + * Only those characters specified in the C++ Language Standard basic source character set shall be used in the source code except within the text of a wide string. + * In general, prefer C++ over C, though exceptions may be granted if needed + * This list of style items is not exhaustive, and some best practices such as include guards will also be checked in our PR reviews. * Doxygen should compile with no warnings when run at the root of the project with the command `doxygen doxyfile` * Absolutely no code shall be added that is under a more strict license than MIT or which has not had conditions met to be distributed under our license * Builds must pass the compilation github action @@ -59,7 +59,7 @@ VS Code can be installed via the snap store, or by downloading it from [Microsof Clone the repo: -``` +```bash git clone https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git ``` diff --git a/README.md b/README.md index 03c4531c..11ffb995 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Check out the [tutorial website](https://isobus-plus-plus.readthedocs.io/en/late This library is compiled with CMake. -``` +```bash cmake -S . -B build cmake --build build ``` @@ -51,7 +51,8 @@ If your target hardware is not listed above, you can easily integrate your own h There are build in examples. By default, examples are not built. The easiest way to build them is from the top level. -``` + +```bash cmake -S . -B build -DBUILD_EXAMPLES=ON cmake --build build ``` @@ -59,7 +60,8 @@ cmake --build build ## Tests Tests are run with GTest. They can be invoked through ctest. Once the library is compiled, navigate to the build directory to run tests. -``` + +```bash cmake -S . -B build -DBUILD_TESTING=ON cmake --build build cd build @@ -73,12 +75,14 @@ You can integrate this library into your own project with CMake if you want. Mul Make sure you have CMake and Git installed: Ubuntu: -``` + +```bash sudo apt install cmake git ``` RHEL: -``` + +```bash sudo dnf install cmake git ``` @@ -92,14 +96,15 @@ Adding this library as a submodule to your project is one of the easier ways to Submodule the repository into your project: -``` +```bash git submodule add https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git git submodule update --init --recursive ``` + Then, if you're using CMake, make sure to add the submodule to your project, and link it. It is recommended to use the ALIAS targets exposed, which all follow the name `isobus::`. -``` +```cmake find_package(Threads) add_subdirectory() @@ -116,17 +121,17 @@ If you don't want to use Git submodules, you can also easily integrate this libr 1. Create a folder called `cmake` in your project if you don't already have one. 2. Inside the `cmake` folder, create a file with the following contents: -``` -if(NOT TARGET isobus::Isobus) - include(FetchContent) - FetchContent_Declare( - AgIsoStack - GIT_REPOSITORY https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git - GIT_TAG main - ) - FetchContent_MakeAvailable(AgIsoStack) -endif() -``` + ```cmake + if(NOT TARGET isobus::Isobus) + include(FetchContent) + FetchContent_Declare( + AgIsoStack + GIT_REPOSITORY https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git + GIT_TAG main + ) + FetchContent_MakeAvailable(AgIsoStack) + endif() + ``` 3. In your top-level CMakeLists.txt file, add `list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/cmake)` after your `project` command 4. In your top-level CMakeLists.txt file, add `find_package(AgIsoStack MODULE)` after the above line. @@ -140,17 +145,22 @@ We do not officially distribute this library in binary form (DLL files, for exam ### Installing The Library -You can also install the library if you want. - -For a local install: +You can also install the library if you want. First, from the top level directory, build AgIsoStack-plus-plus normally +```bash +cmake -S . -B build +cmake --build build ``` + +For a local install, we set it to a known location + +```bash cmake --install build --prefix install ``` For a system-wide install: -``` +```bash sudo cmake --install build ``` @@ -158,7 +168,7 @@ Then, use a call to `find_package()` to find this package. ### Use of our SAE/ISOBUS Manufacturer Code -If you are integrating with our library to create an ISO11783 or J1939 application and are not selling your software or device containing that software for-profit, then you are welcome to use our manufacturer number in your application. +If you are integrating with our library to create an ISO11783 or J1939 application and are not selling your software or device containing that software for-profit, then you are welcome to use our manufacturer number in your application. If you are creating such an application for sale as a for-profit company, then we ask that you please obtain your own manufacturer code from SAE instead of using ours. @@ -166,26 +176,29 @@ Our manufacturer code is 1407 (decimal). ## Documentation -You can view the pre-compiled doxygen here https://delgrossoengineering.com/isobus-docs +You can view the pre-compiled doxygen here You can also generate the doxygen documentation yourself by running the `doxygen` command inside this repo's folder. Make sure you have the prerequisites installed: Ubuntu: -``` + +```bash sudo apt install doxygen graphviz ``` RHEL: -``` + +```bash sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms sudo dnf install doxygen graphviz ``` Then, generate the docs: -``` + +```bash doxygen doxyfile ``` diff --git a/examples/README.md b/examples/README.md index d30e6dfd..6da6ef4f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,32 +1,44 @@ # Examples -The examples here can all be build from top level. -Another approach, more akin to how most consumers would use it, is to install the ISO11783 CAN Stack library. -Then, use a call to `find_package()` to find this package. +This directory contains examples of how to use the AgIsoStack library. -The same process can be used for all examples, however `diagnostic_protocol` is just shown as a reference. +## Building all examples -First, build AgIsoStack-plus-plus. +The examples here can all be build simultaneously from the top level directory of the repository: + +```bash +cmake -S . -B build -DBUILD_EXAMPLES=ON +cmake --build build ``` -# Build the library like normal -cd /path/to/root/directory/of/AgIsoStack-plus-plus + +## Building a single example + +Another approach, more akin to how most consumers would use the library, is to install the AgIsoStack first. +And then, use a call to `find_package()` to find this installation. + +First, from the top level directory, build AgIsoStack-plus-plus normally + +```bash cmake -S . -B build cmake --build build -# Install it locally in a directory called "install" -cmake --install build --prefix install ``` +We install it to a known location, here we use `install` folder relative to the root of the repository as an example. -Now, build an example of your choosing. +```bash +cmake --install build --prefix install ``` -# Now, go in and build the example + +Now, build an example of your choosing, here we use the `diagnostic protocol` as an example, but any of the examples will work. Note that we need to tell CMake where to find the installed package, which is two directories up from the example directory. Hence, the `../../install` argument to `CMAKE_PREFIX_PATH`. + +```bash cd examples/diagnostic_protocol -# Here, because we installed locally, you must supply the path to install cmake -S . -B build -DCMAKE_PREFIX_PATH=../../install cmake --build build ``` -Finally, run the example. +Then, run the example. The name of the executable will be different depending on which example you built. + +```bash +./build/DiagnosticProtocolExample ``` -./build/DiagnosticProtocolExampleTarget -``` \ No newline at end of file diff --git a/hardware_integration/lib/README.md b/hardware_integration/lib/README.md index 10bd89b1..740cf265 100644 --- a/hardware_integration/lib/README.md +++ b/hardware_integration/lib/README.md @@ -1,8 +1,8 @@ -## 3rd Party Drivers +# 3rd Party Drivers -### PEAK PCAN Basic Driver +## PEAK PCAN Basic Driver Please read the End User License Agreement of the company PEAK-System Technik GmbH at: -www.peak-system.com/quick/eula + Use of the PEAK driver libraries is governed by their EULA. diff --git a/sphinx/README.md b/sphinx/README.md index 822f992b..ea99b036 100644 --- a/sphinx/README.md +++ b/sphinx/README.md @@ -6,7 +6,7 @@ You can build the tutorial yourself if you wish. ## Install Prerequisites -``` +```bash pip install sphinx pip install sphinx-rtd-theme ``` @@ -15,13 +15,13 @@ pip install sphinx-rtd-theme Windows: -``` +```bash ./make html ``` Linux: -``` +```bash make html ```