From ea00e56e923edd5a021fb5a2e5013b30fa12a15e Mon Sep 17 00:00:00 2001 From: hhenry01 Date: Sun, 17 Dec 2023 23:23:17 -0800 Subject: [PATCH] Update README and license --- LICENSE | 17 +++++++++++ README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..30e8e2e --- /dev/null +++ b/LICENSE @@ -0,0 +1,17 @@ +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 1e0a0c4..ec9b76d 100755 --- a/README.md +++ b/README.md @@ -1,5 +1,90 @@ # Network Systems +[![Tests](https://github.com/UBCSailbot/network_systems/actions/workflows/tests.yml/badge.svg)](https://github.com/UBCSailbot/network_systems/actions/workflows/tests.yml) + This repository contains the source code for all of UBC Sailbot's Network Systems programs. It is made to work as part of [Sailbot Workspace](https://github.com/UBCSailbot/sailbot_workspace), and is **_not_** meant to be built as an independent project. + +## Setup + +For comprehensive setup instructions, follow our [setup guide](https://ubcsailbot.github.io/docs/main/current/sailbot_workspace/setup/). + +## Building + +**Option A**: With sailbot_workspace open, invoke the VSCode `build` or `debug` task. + +**Option B**: Run `/workspaces/sailbot_workspace/build.sh` + +## Running + +### ROS Launch + +[Instructions found here.](https://ubcsailbot.github.io/docs/main/current/sailbot_workspace/launch_files/) + +For example: + +```bash +ros2 launch network_systems main_launch.py +``` + +This is the best option if multiple modules need to be run at once. Launch configurations are found under the +[config](config/) folder. These configurations define which modules to enable/disable and what parameters to use. + +### ROS Run + +If you just want to run a single module, then this is a direct and easy way to do it. + +For example: + +```bash +ros2 run network_systems example --ros-args -p enabled:=true +``` + +### Binary + +Not recommended as you cannot pass ROS parameters, so modules may not work by default. Binaries for each module found +under [projects](projects/) can be found under +`/workspaces/sailbot_workspace/build/network_systems/projects/{module_name}/{module_name}`. + +For example: + +```bash +/workspaces/sailbot_workspace/build/network_systems/projects/example/example +``` + +## Testing + +Unit tests specific to Network Systems is done using [GoogleTest](https://github.com/google/googletest). Unit tests +are defined per module. For example, under [projects/example/test/](projects/example/test/test_cached_fib.cpp). + +### Run All Tests + +**Option A**: With sailbot_workspace open, invoke the VSCode `test` task. + +**Option B**: Under the sailbot_workspace directory, run `/workspaces/sailbot_workspace/test.sh` + +Both options will run all of UBC Sailbot's tests, including those from other projects. More often than not, this is +unnecessary. + +### Run and Debug Specific Tests + +This is the preferred way to run and debug tests. When you open a test source file like +[the example's](projects/example/test/test_cached_fib.cpp), there will be green arrows next to each `TEST_F` macro. +Clicking a double green arrow runs a test suite, while clicking single green arrow runs one unit test. Right clicking +either arrow will open a prompt with a debug test option. When running a test via the debug option, we can set +breakpoints and step through our code line by line to resolve issues. + +This convenient testing frontend is thank's to the +[TestMate extension](https://marketplace.visualstudio.com/items?itemName=matepek.vscode-catch2-test-adapter). + +### Run Test Binaries + +Test binaries for each module found under projects can be found under +`/workspaces/sailbot_workspace/build/network_systems/projects/{module_name}/test_{module_name}`. + +For example: + +```bash +/workspaces/sailbot_workspace/build/network_systems/projects/example/test_example +```