diff --git a/.dir-locals.el b/.dir-locals.el index 96e0817c..f8c3c5e2 100644 --- a/.dir-locals.el +++ b/.dir-locals.el @@ -35,23 +35,51 @@ (add-to-list 'flycheck-clang-args "-fPIC") (add-to-list 'flycheck-clang-args "-std=c++17") (add-to-list 'flycheck-clang-args "-Wno-pragma-once-outside-header") - (add-to-list 'flycheck-clang-definitions "COSM_ENABLE_PAL_TARGET_ROS") + (add-to-list 'flycheck-clang-definitions + "COSM_ENABLE_PAL_TARGET_ARGOS") + ;; (add-to-list 'flycheck-clang-definitions + ;; "COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_FOOTBOT") + (add-to-list 'flycheck-clang-definitions + "COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_DRONE") + (add-to-list 'flycheck-clang-definitions + "COSM_HAL_TARGET_HAS_QUADROTOR") + (add-to-list 'flycheck-clang-definitions + "COSM_HAL_TARGET_HAS_2D_BINDINGS") + (add-to-list 'flycheck-clang-definitions + "COSM_HAL_TARGET_HAS_3D_BINDINGS") - (add-to-list 'flycheck-clang-definitions "LIBRA_ER=LIBRA_ER_ALL") - (add-to-list 'flycheck-clang-definitions "RCPPSW_ER_SYSTEM_LOG4CXX") - (add-to-list 'flycheck-clang-args (concat "-isystem" (substitute-in-file-name - "$localroot/system/include"))) + (add-to-list 'flycheck-clang-definitions + "LIBRA_ER=LIBRA_ER_ALL") + (add-to-list 'flycheck-clang-definitions + "RCPPSW_ER_SYSTEM_LOG4CXX") + (add-to-list 'flycheck-clang-args + (concat "-isystem" (substitute-in-file-name + "$localroot/system/include"))) (setq flycheck-gcc-include-path includes-list) (add-to-list 'flycheck-gcc-args "-fPIC") (add-to-list 'flycheck-gcc-args "-std=c++17") - (add-to-list 'flycheck-gcc-definitions "COSM_ENABLE_PAL_TARGET_ROS") - (add-to-list 'flycheck-gcc-definitions "RCPPSW_ER_SYSTEM_LOG4CXX") - (add-to-list 'flycheck-gcc-definitions "LIBRA_ER=LIBRA_ER_ALL") + (add-to-list 'flycheck-gcc-definitions + "COSM_ENABLE_PAL_TARGET_ARGOS") + (add-to-list 'flycheck-gcc-definitions + "COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_DRONE") + (add-to-list 'flycheck-gcc-definitions + "COSM_HAL_TARGET_HAS_QUADROTOR") + (add-to-list 'flycheck-gcc-definitions + "COSM_HAL_TARGET_HAS_2D_BINDINGS") + (add-to-list 'flycheck-gcc-definitions + "COSM_HAL_TARGET_HAS_3D_BINDINGS") + ;; (add-to-list 'flycheck-gcc-definitions + ;; "COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_FOOTBOT") + (add-to-list 'flycheck-gcc-definitions + "RCPPSW_ER_SYSTEM_LOG4CXX") + (add-to-list 'flycheck-gcc-definitions + "LIBRA_ER=LIBRA_ER_ALL") - (add-to-list 'flycheck-gcc-args (concat "-isystem" (substitute-in-file-name - "$localroot/system/include"))) + (add-to-list 'flycheck-gcc-args + (concat "-isystem" (substitute-in-file-name + "$localroot/system/include"))) (let ((cc-search-dirs (list (concat (projectile-project-root) "include/cosm/*/*") (concat (projectile-project-root) "src/*/*") @@ -61,6 +89,15 @@ ) ) )) - )) + ) + (nil . ((eval . + (progn + (add-to-list 'projectile-globally-ignored-directories + "docs/doxyoutput") + ) + )) + ) + + ) ;;; end of .dir-locals.el diff --git a/.github/actions/rcppsw-setup/action.yml b/.github/actions/rcppsw-setup/action.yml new file mode 100644 index 00000000..e538ff2f --- /dev/null +++ b/.github/actions/rcppsw-setup/action.yml @@ -0,0 +1,36 @@ +name: 'Setup RCPPSW' +description: 'Setup RCPPSW for CI and testing' +inputs: + cmake_extra_args: # id of input + description: 'Extra arguments to pass to cmake' + required: True +# outputs: +# time: # id of output +# description: 'The time we greeted you' +runs: + using: 'composite' + steps: + - name: Install RCPPSW + shell: bash + run: | + echo ${{ inputs.cmake_extra_args }} + + mkdir -p build && cd build + git clone https://github.com/jharwell/rcppsw.git + cd rcppsw + + git config --global --add safe.directory $PWD + git checkout devel + git submodule update --init --remote --recursive + mkdir build && cd build + + cmake \ + -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DLIBRA_DEPS_PREFIX=/usr/local \ + -DCMAKE_BUILD_TYPE=DEV \ + -DLIBRA_ER=ALL ${{ inputs.cmake_extra_args }} \ + .. + + JOBS=$(grep -c ^processor /proc/cpuinfo) + make ticpp + make -j${JOBS} install diff --git a/.github/actions/rcsw-setup/action.yml b/.github/actions/rcsw-setup/action.yml new file mode 100644 index 00000000..f3116513 --- /dev/null +++ b/.github/actions/rcsw-setup/action.yml @@ -0,0 +1,33 @@ +name: 'Setup RCSW' +description: 'Setup RCSW for CI and testing' +# inputs: + # who-to-greet: # id of input + # description: 'Who to greet' + # required: true + # default: 'World' +# outputs: +# time: # id of output +# description: 'The time we greeted you' +runs: + using: 'composite' + steps: + - name: Install RCSW + shell: bash + run: | + mkdir -p build && cd build + git clone https://github.com/jharwell/rcsw.git + cd rcsw + + git config --global --add safe.directory $PWD + git checkout devel + git submodule update --init --remote --recursive + mkdir build && cd build + + cmake \ + -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DLIBRA_DEPS_PREFIX=/usr/local \ + -DCMAKE_BUILD_TYPE=DEV \ + .. + + JOBS=$(grep -c ^processor /proc/cpuinfo) + make -j${JOBS} install diff --git a/.github/workflows/ci-argos.yml b/.github/workflows/ci-argos.yml new file mode 100644 index 00000000..3d316b82 --- /dev/null +++ b/.github/workflows/ci-argos.yml @@ -0,0 +1,47 @@ +name: ARGoS build and test + +on: + workflow_call: + workflow_dispatch: + +concurrency: + group: ${{ github.ref }} + cancel-in-progress: true + +jobs: + build-and-test-argos: + runs-on: ubuntu-latest + container: + image: jharwell/ubuntu22.04:2023-03-23 + strategy: + matrix: + CMAKE_BUILD_TYPE: + - OPT + - DEV + COSM_BUILD_FOR: + - ARGOS_FOOTBOT + - ARGOS_DRONE + + steps: + - uses: actions/checkout@v3 + - uses: ./.github/actions/rcsw-setup + - uses: ./.github/actions/rcppsw-setup + with: + cmake_extra_args: '' + - name: Build=${{ matrix.CMAKE_BUILD_TYPE }} HAL_TARGET=${{ matrix.COSM_BUILD_FOR }} + shell: bash + run: | + + git config --global --add safe.directory $PWD + git submodule update --init --remote --recursive + mkdir -p build && cd build + + cmake \ + -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DLIBRA_DEPS_PREFIX=/usr/local \ + -DCMAKE_BUILD_TYPE=${{ matrix.CMAKE_BUILD_TYPE }} \ + -DLIBRA_ER=ALL \ + -DCOSM_BUILD_FOR=${{ matrix.COSM_BUILD_FOR }} \ + .. + + make -j$(nproc) diff --git a/.github/workflows/ci-ros1.yml b/.github/workflows/ci-ros1.yml new file mode 100644 index 00000000..068fa583 --- /dev/null +++ b/.github/workflows/ci-ros1.yml @@ -0,0 +1,49 @@ +name: ROS1 build and test + +on: + workflow_dispatch: + workflow_call: + +concurrency: + group: ${{ github.ref }} + cancel-in-progress: true + +jobs: + build-and-test-ros1: + runs-on: ubuntu-latest + container: + image: jharwell/ubuntu20.04:2023-03-28 + strategy: + matrix: + CMAKE_BUILD_TYPE: + - OPT + - DEV + COSM_BUILD_FOR: + - ROS_ETURTLEBOT3 + + steps: + - uses: actions/checkout@v3 + - uses: ./.github/actions/rcsw-setup + - uses: ./.github/actions/rcppsw-setup + with: + cmake_extra_args: '-DRCPPSW_ER_OLD_LOG4CXX=YES' + + - name: Build=${{ matrix.CMAKE_BUILD_TYPE }} HAL_TARGET=${{ matrix.COSM_BUILD_FOR }} + shell: bash + run: | + + git config --global --add safe.directory $PWD + git submodule update --init --remote --recursive + mkdir -p build && cd build + + source /opt/ros/noetic/setup.bash + + cmake \ + -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DLIBRA_DEPS_PREFIX=/usr/local \ + -DCMAKE_BUILD_TYPE=${{ matrix.CMAKE_BUILD_TYPE }} \ + -DLIBRA_ER=ALL \ + -DCOSM_BUILD_FOR=${{ matrix.COSM_BUILD_FOR }} \ + .. + + make -j$(nproc) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..05c5887b --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,61 @@ +name: Build and test + +on: + push: + branches: + - master + - devel + +concurrency: + group: ${{ github.ref }} + cancel-in-progress: true + +jobs: + argos-ci: + uses: ./.github/workflows/ci-argos.yml + ros1-ci: + uses: ./.github/workflows/ci-ros1.yml + + docs: + uses: ./.github/workflows/pages.yml + needs: + - build-and-test-argos + - build-and-test-ros1 + secrets: inherit + + tag-release: + runs-on: ubuntu-latest + needs: + - build-and-test-argos + - build-and-test-ros1 + + container: + image: jharwell/ubuntu22.04:2023-03-23 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + steps: + - uses: actions/checkout@v3 + + - name: Push tag + shell: bash + run: | + git config --global --add safe.directory $PWD + git config --global user.email "${{ github.event.pusher.email }}" + git config --global user.name "${{ github.event.pusher.name }}" + + git submodule update --init --remote --recursive + + VERSION_MAJOR=$(sed -nE 's/.*PROJECT_VERSION_MAJOR ([0-9]+).*/\1/p' cmake/project-local.cmake) + VERSION_MINOR=$(sed -nE 's/.*PROJECT_VERSION_MINOR ([0-9]+).*/\1/p' cmake/project-local.cmake) + VERSION_PATCH=$(sed -nE 's/.*PROJECT_VERSION_PATCH ([0-9]+).*/\1/p' cmake/project-local.cmake) + PACKAGE_VERSION=$VERSION_MAJOR.$VERSION_MINOR.$VERSION_PATCH + + if [ "${{ github.ref }}" = "refs/heads/devel" ]; then + TAG_VERSION=${PACKAGE_VERSION}.beta + TAG_MESSAGE="Development release ${TAG_VERSION}" + else + TAG_VERSION=${PACKAGE_VERSION} + TAG_MESSAGE="Release ${TAG_VERSION}" + fi + git tag ${TAG_VERSION} -m "${TAG_MESSAGE}" + git push -o ci.skip origin ${TAG_VERSION} diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 00000000..7f2f67f3 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,70 @@ +# Simple workflow for deploying static content to GitHub Pages +name: docs + +on: + workflow_call: + # Runs on pushes targeting the default branch + # push: + # branches: + # - master + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + container: + image: jharwell/ubuntu22.04:2023-03-23 + steps: + - uses: actions/checkout@v3 + - uses: ./.github/actions/rcsw-setup + - uses: ./.github/actions/rcppsw-setup + - name: Setup Pages + id: pages + uses: actions/configure-pages@v3 + + - shell: bash + run: | + + git config --global --add safe.directory $PWD + git submodule update --init --remote --recursive + mkdir -p build && cd build + + cmake \ + -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DCMAKE_BUILD_TYPE=DEV \ + -DCOSM_BUILD_FOR=ARGOS_FOOTBOT \ + .. + make apidoc + + cd .. + cd docs && make html + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: ./docs/_build/html + + deploy: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/.gitignore b/.gitignore index 364616ad..d493c206 100644 --- a/.gitignore +++ b/.gitignore @@ -51,5 +51,5 @@ node_modules # Sphinx docs/_build/ -docs/api +docs/_api docs/_ext/__pycache__ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 00000000..d4c2797f --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,224 @@ +default: + image: docker.sift.net/jharwell/rcppsw/ubuntu-22.04:latest + +before_script: + # Run minimal bootstrap to get TICPP + - git clone https://gitlab-deploy-token:${BOOTSTRAP_DEPLOY_TOKEN}@git.sift.net/jharwell/bootstrap.git + - cd bootstrap + - ./bootstrap.sh + --rprefix=/usr/local + --sysprefix=/usr/local + --rroot=. + --disablerepo rcsw + --disablerepo rcppsw + --disablerepo cosm + --disablerepo fordyca + --disablerepo argos + --disablerepo sierra + --disablerepo titerra + --force + + - cd .. + + # Install RCSW so RCPPSW can find it + - git clone https://oauth2:${JHARWELL_CI_TOKEN}@git.sift.net/jharwell/rcsw.git + - cd rcsw + - git checkout devel + - git submodule set-url libra ../libra.git + - git submodule sync --recursive + - git submodule foreach --recursive git fetch + - git submodule update --init + - mkdir build && cd build + - cmake + -DCMAKE_INSTALL_PREFIX=/usr/local + -DLIBRA_DEPS_PREFIX=/usr/local + -DCMAKE_BUILD_TYPE=DEV + .. + + - JOBS=$(nproc) + - make -j${JOBS} install + - cd ../../ + + # Install RCPPSW so COSM can find it + - git clone https://oauth2:${JHARWELL_CI_TOKEN}@git.sift.net/jharwell/rcppsw.git + - cd rcppsw + - git checkout devel + - git submodule set-url libra ../libra.git + - git submodule sync --recursive + - git submodule foreach --recursive git fetch + - git submodule update --init + - mkdir build && cd build + - cmake + -DCMAKE_INSTALL_PREFIX=/usr/local + -DLIBRA_DEPS_PREFIX=/usr/local + -DCMAKE_BUILD_TYPE=DEV + -DLIBRA_ER=ALL + .. + + - make -j${JOBS} install + - cd ../.. + +# If all tests pass, deploy. +stages: + - build-and-test + - package-and-deploy + +################################################################################ +# Job to build and run tests +################################################################################ +build-and-test: + tags: + - docker + stage: build-and-test + parallel: + matrix: + - COSM_BUILD_FOR: + - ARGOS_FOOTBOT + - ARGOS_DRONE + + script: + # Build COSM + - git submodule set-url libra ../libra.git + - git submodule sync --recursive + - git submodule foreach --recursive git fetch + - git submodule update --init + + - mkdir -p build && cd build + + - cmake + -DCMAKE_INSTALL_PREFIX=/usr/local + -DLIBRA_DEPS_PREFIX=/usr/local + -DCMAKE_BUILD_TYPE=DEV + -DCOSM_BUILD_FOR=${COSM_BUILD_FOR} + -DLIBRA_ER=ALL + .. + + - make -j$(nproc) + +################################################################################ +# Jobs to build and upload packages +################################################################################ +package-and-deploy: + stage: package-and-deploy + parallel: + tags: + - docker + + only: + - master + - devel + + script: + - git submodule set-url libra ../libra.git + - git submodule sync --recursive + - git submodule foreach --recursive git fetch + - git submodule update --init + + - mkdir -p build && cd build + + # Metadata for packaging + - JOBS=$(nproc) + - VERSION_MAJOR=$(sed -nE 's/.*PROJECT_VERSION_MAJOR ([0-9]+).*/\1/p' ../cmake/project-local.cmake) + - VERSION_MINOR=$(sed -nE 's/.*PROJECT_VERSION_MINOR ([0-9]+).*/\1/p' ../cmake/project-local.cmake) + - VERSION_PATCH=$(sed -nE 's/.*PROJECT_VERSION_PATCH ([0-9]+).*/\1/p' ../cmake/project-local.cmake) + - PACKAGE_VERSION=$VERSION_MAJOR.$VERSION_MINOR.$VERSION_PATCH + - PACKAGE_REGISTRY_URL="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/COSM/${PACKAGE_VERSION}" + + # Build for ARGoS foot-bot and create packages + - cmake + -DCMAKE_INSTALL_PREFIX=/usr/local + -DLIBRA_DEPS_PREFIX=/usr/local + -DCOSM_BUILD_FOR=ARGOS_FOOTBOT + -DLIBRA_ER=ALL + .. + + - make -j${JOBS} + - make package + + # Upload ARGoS foot-bot packages + - ARGOS_FOOTBOT_DEB=$(ls cosm-argos-footbot*.deb) + - ARGOS_FOOTBOT_TGZ=$(ls cosm-argos-footbot*.tar.gz) + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file ${ARGOS_FOOTBOT_DEB} ${PACKAGE_REGISTRY_URL}/${ARGOS_FOOTBOT_DEB} + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file ${ARGOS_FOOTBOT_TGZ} ${PACKAGE_REGISTRY_URL}/${ARGOS_FOOTBOT_TGZ} + + # Build for ARGoS drone and create packages + - cmake + -DCMAKE_INSTALL_PREFIX=/usr/local + -DLIBRA_DEPS_PREFIX=/usr/local + -DCOSM_BUILD_FOR=ARGOS_DRONE + -DLIBRA_ER=ALL + .. + + - make -j${JOBS} + - make package + + # Upload ARGoS drone packages + - ARGOS_DRONE_DEB=$(ls cosm-argos-drone*.deb) + - ARGOS_DRONE_TGZ=$(ls cosm-argos-drone*.tar.gz) + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file ${ARGOS_DRONE_DEB} ${PACKAGE_REGISTRY_URL}/${ARGOS_DRONE_DEB} + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file ${ARGOS_DRONE_TGZ} ${PACKAGE_REGISTRY_URL}/${ARGOS_DRONE_TGZ} + + + # Push tag (after building to make double sure we only ever push stuff that + # at least builds) + - BETA_TAG_VERSION=${PACKAGE_VERSION}.beta + - BETA_TAG_MESSAGE="Development release ${BETA_TAG_VERSION}" + - git config --global user.email "${GITLAB_USER_EMAIL}" + - git config --global user.name "${GITLAB_USER_NAME}" + - git remote set-url origin https://oauth2:${JHARWELL_CI_TOKEN}@git.sift.net/${CI_PROJECT_PATH} + - git tag $BETA_TAG_VERSION -m "${BETA_TAG_MESSAGE}" + - git push -o ci.skip origin ${BETA_TAG_VERSION} # don't trigger another run + + # Create the release + - curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-linux-amd64" + - chmod +x /usr/local/bin/release-cli + - release-cli + create + --name ${BETA_TAG_VERSION} + --tag-name ${BETA_TAG_VERSION} + --description "${BETA_TAG_MESSAGE}" + --assets-link "{\"name\":\"${ARGOS_FOOTBOT_DEB}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${ARGOS_FOOTBOT_DEB}\"}" + --assets-link "{\"name\":\"${ARGOS_FOOTBOT_TGZ}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${ARGOS_FOOTBOT_TGZ}\"}" + --assets-link "{\"name\":\"${ARGOS_DRONE_DEB}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${ARGOS_DRONE_DEB}\"}" + --assets-link "{\"name\":\"${ARGOS_DRONE_TGZ}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${ARGOS_DRONE_TGZ}\"}" + +################################################################################ +# Job to build documentation +################################################################################ +pages: + stage: package-and-deploy + tags: + - docker + + only: + - master + - devel + + script: + - git submodule set-url libra ../libra.git + - git submodule sync --recursive + - git submodule foreach --recursive git fetch + - git submodule update --init + + - mkdir -p build && cd build + + - cmake + -DCMAKE_INSTALL_PREFIX=/usr/local + -DCOSM_BUILD_FOR=ARGOS_FOOTBOT + .. + + - make apidoc + + - cd .. + - export PATH=$PATH:$HOME/.local/bin + + - cd docs && make html && cd .. + - cp -r docs/_build/html/ ./public/ + + artifacts: + paths: + - public diff --git a/.gitmodules b/.gitmodules index ffa94f2e..70e62c43 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "libra"] path = libra - url = https://github.com/swarm-robotics/libra.git + url = https://github.com/jharwell/libra.git branch = devel diff --git a/LICENSE.md b/LICENSE similarity index 100% rename from LICENSE.md rename to LICENSE diff --git a/README.rst b/README.rst index cc5be515..a4424a5e 100644 --- a/README.rst +++ b/README.rst @@ -4,21 +4,41 @@ COSM (Core Swarm) ================= +.. |ci-master| image:: https://github.com/jharwell/cosm/actions/workflows/ci.yml/badge.svg?branch=master +.. |ci-master-ros1| image:: https://github.com/jharwell/cosm/actions/workflows/ci-ros1.yml/badge.svg?branch=master +.. |ci-master-argos| image:: https://github.com/jharwell/cosm/actions/workflows/ci-argos.yml/badge.svg?branch=master + +.. |ci-devel| image:: https://github.com/jharwell/cosm/actions/workflows/ci.yml/badge.svg?branch=devel +.. |ci-devel-ros1| image:: https://github.com/jharwell/cosm/actions/workflows/ci-ros1.yml/badge.svg?branch=devel +.. |ci-devel-argos| image:: https://github.com/jharwell/cosm/actions/workflows/ci-argos.yml/badge.svg?branch=devel + .. |license| image:: https://img.shields.io/github/license/jharwell/cosm - :target: https://img.shields.io/github/license/jharwell/cosm + :target: https://img.shields.io/github/license/jharwell/cosm -.. |docs| image:: https://readthedocs.org/projects/cosm/badge/?version=master - :target: https://cosm.readthedocs.io/en/master/?badge=master +.. |docs| image:: https://github.com/jharwell/cosm/actions/workflows/pages.yml/badge.svg?branch=master + :target: https://jharwell.github.io/cosm .. |maintenance| image:: https://img.shields.io/badge/Maintained%3F-yes-green.svg -|license| |docs| |maintenance| + + +:Release: + + |ci-master| |ci-master-ros1| |ci-master-argos| + +:Development: + + |ci-devel| |ci-devel-ros1| |ci-devel-argos| + +:Misc: + + |license| |docs| |maintenance| This is a collection of non application, method, or controller specific software components that can be reused across multiple swarm robotics projects (i.e., generic in the context of swarm-robotics, but maybe not more broadly). -Project documentation is here: ``_. +Project documentation is here: ``_. License ======= diff --git a/cmake/argos.cmake b/cmake/argos.cmake new file mode 100644 index 00000000..5bae2493 --- /dev/null +++ b/cmake/argos.cmake @@ -0,0 +1,71 @@ +# +# Copyright 2022 John Harwell, All rights reserved. +# +# SPDX-License-Identifier: MIT +# +macro(cosm_argos_configure_components) + string(CONCAT argos_regex + "src/ds|" + "src/arena|" + "src/convergence|" + "src/fsm|" + "src/hal/argos/subsystem|" + "src/hal/argos/sensors|" + "src/metrics|" + "src/oracle|" + "src/pal/argos|" + "src/repr|" + "src/spatial/common|" + "src/spatial/fsm|" + "src/foraging|" + "src/spatial/metrics|" + + # While these are really for 2D agents, they compile OK for flying + # agents and could theoretically be used in that context someday. + "src/spatial/strategy/base|" + "src/spatial/strategy/nest|" + "src/spatial/strategy/explore|" + + "src/tv|" + "src/argos" + ) + + if(${COSM_HAL_TARGET_OPERATES_IN_Q3D}) + # Foraging is a ground robot only thing in ARGoS. + string(CONCAT argos_regex + "${argos_regex}|" + "${Q3D_bindings_regex}|" + "src/spatial/strategy/blocks") + endif() + + if(${COSM_HAL_TARGET_OPERATES_IN_3D}) + string(CONCAT argos_regex + "${argos_regex}|" + "${3D_bindings_regex}") + endif() + + libra_component_register_as_src( + cosm_argos_SRC + cosm + "${cosm_SRC}" + argos + "${argos_regex}") + + if(COSM_WITH_VIS) + libra_component_register_as_src( + cosm_argos_vis_SRC + cosm + "${cosm_SRC}" + argos_vis + "src/argos/vis") + endif() + + # Root project (not used in find_package()) + if (NOT cosm_FIND_COMPONENTS) + set(cosm_FIND_COMPONENTS + common + argos + argos_vis + ) + endif() +endmacro() diff --git a/cmake/config.cmake.in b/cmake/config.cmake.in index 8bb11556..52e4458a 100644 --- a/cmake/config.cmake.in +++ b/cmake/config.cmake.in @@ -1,5 +1,9 @@ @PACKAGE_INIT@ +set(cosm_VERSION @cosm_VERSION@) +set(cosm_INSTALL_PREFIX @CMAKE_INSTALL_PREFIX@) +set(cosm_INCLUDE_DIRS ${cosm_INSTALL_PREFIX}/include) + set(COSM_HAL_TARGET @COSM_HAL_TARGET@) set(COSM_BUILD_FOR @COSM_BUILD_FOR@) set(COSM_WITH_VIS @COSM_WITH_VIS@) @@ -16,6 +20,7 @@ set(COSM_ROS_ROBOT_NAME_PREFIX @COSM_ROS_ROBOT_NAME_PREFIX@) set(COSM_ROS_CONTROLLER_XML_ID @COSM_ROS_CONTROLLER_XML_ID@) set(COSM_ROS_MD5 @COSM_ROS_MD5@) + if(COSM_WITH_VIS) set(CMAKE_AUTOMOC ON) find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Widgets Gui REQUIRED) @@ -25,8 +30,6 @@ if(COSM_WITH_VIS) find_package(OpenGL REQUIRED) endif() -set(cosm_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}) - if(NOT TARGET rcppsw::rcppsw) find_package(rcppsw HINTS ${cosm_INSTALL_PREFIX}) @@ -44,7 +47,6 @@ endif() include("${CMAKE_CURRENT_LIST_DIR}/cosm-@COSM_HAL_TARGET@-exports.cmake") -set(cosm_INCLUDE_DIRS ${cosm_INSTALL_PREFIX}/include) check_required_components("COSM") diff --git a/cmake/cosm-config-summary.cmake b/cmake/cosm-config-summary.cmake index afbc2235..669d1510 100644 --- a/cmake/cosm-config-summary.cmake +++ b/cmake/cosm-config-summary.cmake @@ -1,9 +1,11 @@ function(cosm_config_summary ) - message(STATUS "") - message(STATUS "") - message(STATUS "COSM Configuration Summary:") - message(STATUS "") + message("") + message("--------------------------------------------------------------------------------") + message(" COSM Configuration Summary") + message("--------------------------------------------------------------------------------") + message("") + message(STATUS "Build version.........................: COSM_VERSION=${cosm_VERSION}") message(STATUS "Build environment.....................: COSM_BUILD_ENV=${COSM_BUILD_ENV}") message(STATUS "Building for..........................: COSM_BUILD_FOR=${COSM_BUILD_FOR}") message(STATUS "Platform..............................: COSM_PAL_TARGET=${COSM_PAL_TARGET}") @@ -17,4 +19,7 @@ function(cosm_config_summary ) message(STATUS "Robot name prefix.....................: COSM_ROS_ROBOT_NAME_PREFIX=${COSM_ROS_ROBOT_NAME_PREFIX}") message(STATUS "Custom msg MD5........................: COSM_ROS_MD5=${COSM_ROS_MD5}") endif() + message("") + message("--------------------------------------------------------------------------------") + endfunction() diff --git a/cmake/hal.cmake b/cmake/hal.cmake new file mode 100644 index 00000000..37928d02 --- /dev/null +++ b/cmake/hal.cmake @@ -0,0 +1,193 @@ +# +# Copyright 2022 John Harwell, All rights reserved. +# +# SPDX-License-Identifier: MIT +# + +################################################################################ +# Define HAL Target +################################################################################ +macro(cosm_hal_configure_target) + if(NOT DEFINED COSM_BUILD_FOR) + set(COSM_BUILD_FOR "ARGOS_FOOTBOT") + message(WARNING "COSM_BUILD_FOR not defined--defaulting to ARGOS_FOOTBOT") + endif() + + if("${COSM_BUILD_FOR}" MATCHES "ARGOS_FOOTBOT") + set(COSM_HAL_TARGET "argos-footbot") + set(COSM_ARGOS_ROBOT_TYPE "foot-bot") + set(COSM_ARGOS_ROBOT_NAME_PREFIX "fb") + set(COSM_ARGOS_CONTROLLER_XML_ID "fbc") + + # define sensors + set(COSM_HAL_TARGET_HAS_IR_SENSOR YES) + set(COSM_HAL_TARGET_HAS_CAMERA_BLOBS_SENSOR YES) + set(COSM_HAL_TARGET_HAS_LIGHT_SENSOR YES) + set(COSM_HAL_TARGET_HAS_BATTERY_SENSOR YES) + set(COSM_HAL_TARGET_HAS_GROUND_SENSOR YES) + set(COSM_HAL_TARGET_HAS_ENV_SENSOR YES) + set(COSM_HAL_TARGET_HAS_PROX_SENSOR YES) + set(COSM_HAL_TARGET_HAS_WIFI_SENSOR YES) + set(COSM_HAL_TARGET_HAS_DIFF_DRIVE_SENSOR YES) + + # define actuators + set(COSM_HAL_TARGET_HAS_DIFF_DRIVE_ACTUATOR YES) + set(COSM_HAL_TARGET_HAS_WIFI_ACTUATOR YES) + + set(COSM_HAL_TARGET_OPERATES_IN_Q3D YES) + + elseif("${COSM_BUILD_FOR}" MATCHES "ARGOS_EEPUCK3D") + set(COSM_HAL_TARGET "argos-eepuck3D") + set(COSM_ARGOS_ROBOT_TYPE "e-puck") + set(COSM_ARGOS_ROBOT_NAME_PREFIX "ep") + set(COSM_ARGOS_CONTROLLER_XML_ID "epc") + + # define sensors + set(COSM_HAL_TARGET_HAS_IR_SENSOR YES) + set(COSM_HAL_TARGET_HAS_CAMERA_BLOBS_SENSOR YES) + set(COSM_HAL_TARGET_HAS_LIGHT_SENSOR YES) + set(COSM_HAL_TARGET_HAS_BATTERY_SENSOR YES) + set(COSM_HAL_TARGET_HAS_GROUND_SENSOR YES) + set(COSM_HAL_TARGET_HAS_ENV_SENSOR YES) + set(COSM_HAL_TARGET_HAS_PROX_SENSOR YES) + + # define actuators + set(COSM_HAL_TARGET_HAS_DIFF_DRIVE_ACTUATOR YES) + + set(COSM_HAL_TARGET_OPERATES_IN_Q3D YES) + + elseif("${COSM_BUILD_FOR}" MATCHES "ARGOS_PIPUCK") + set(COSM_HAL_TARGET "argos-pipuck") + set(COSM_ARGOS_ROBOT_TYPE "pipuck") + set(COSM_ARGOS_ROBOT_NAME_PREFIX "pp") + set(COSM_ARGOS_CONTROLLER_XML_ID "ppc") + + # define sensors + set(COSM_HAL_TARGET_HAS_IR_SENSOR YES) + set(COSM_HAL_TARGET_HAS_CAMERA_BLOBS_SENSOR YES) + set(COSM_HAL_TARGET_HAS_LIGHT_SENSOR YES) + set(COSM_HAL_TARGET_HAS_BATTERY_SENSOR YES) + set(COSM_HAL_TARGET_HAS_GROUND_SENSOR YES) + set(COSM_HAL_TARGET_HAS_ENV_SENSOR YES) + set(COSM_HAL_TARGET_HAS_PROX_SENSOR YES) + + # define actuators + set(COSM_HAL_TARGET_HAS_DIFF_DRIVE_ACTUATOR YES) + + set(COSM_HAL_TARGET_OPERATES_IN_Q3D YES) + + elseif("${COSM_BUILD_FOR}" MATCHES "ARGOS_DRONE") + set(COSM_HAL_TARGET "argos-drone") + set(COSM_ARGOS_ROBOT_TYPE "drone") + set(COSM_ARGOS_ROBOT_NAME_PREFIX "dr") + set(COSM_ARGOS_CONTROLLER_XML_ID "drc") + + # define sensors + set(COSM_HAL_TARGET_HAS_QUADROTOR_SENSOR YES) + + # define actuators + set(COSM_HAL_TARGET_HAS_QUADROTOR_ACTUATOR YES) + + set(COSM_HAL_TARGET_OPERATES_IN_3D YES) + + elseif("${COSM_BUILD_FOR}" MATCHES "ROS_ETURTLEBOT3") + set(COSM_HAL_TARGET "ros-eturtlebot3") + set(COSM_ROS_ROBOT_TYPE "eturtlebot3") + set(COSM_ROS_ROBOT_NAME_PREFIX "etb3_") + + # define sensors + set(COSM_HAL_TARGET_HAS_LIDAR_SENSOR YES) + set(COSM_HAL_TARGET_HAS_LIGHT_SENSOR YES) + set(COSM_HAL_TARGET_HAS_PROX_SENSOR YES) + + # define actuators + set(COSM_HAL_TARGET_HAS_DIFF_DRIVE_ACTUATOR YES) + + set(COSM_HAL_TARGET_OPERATES_IN_Q3D YES) + + else() + set(COSM_BUILD_TARGETS + ARGOS_FOOTBOT + ARGOS_EEPUCK3D + ARGOS_PIPUCK + ARGOS_DRONE + ROS_ETURTLEBOT3 + ) + message(FATAL_ERROR "Build target must be one of ${COSM_BUILD_TARGETS}") + endif() + + set(COSM_HAL_TARGET_SENSOR_SUITE + COSM_HAL_TARGET_HAS_IR_SENSOR + COSM_HAL_TARGET_HAS_LIDAR_SENSOR + COSM_HAL_TARGET_HAS_CAMERA_BLOBS_SENSOR + COSM_HAL_TARGET_HAS_LIGHT_SENSOR + COSM_HAL_TARGET_HAS_ENV_SENSOR + COSM_HAL_TARGET_HAS_BATTERY_SENSOR + COSM_HAL_TARGET_HAS_GROUND_SENSOR + COSM_HAL_TARGET_HAS_QUADROTOR_SENSOR + COSM_HAL_TARGET_HAS_PROX_SENSOR + COSM_HAL_TARGET_HAS_WIFI_SENSOR + COSM_HAL_TARGET_HAS_DIFF_DRIVE_SENSOR + ) + set(COSM_HAL_TARGET_ACTUATOR_SUITE + COSM_HAL_TARGET_HAS_DIFF_DRIVE_ACTUATOR + COSM_HAL_TARGET_HAS_WIFI_ACTUATOR + COSM_HAL_TARGET_HAS_QUADROTOR_ACTUATOR + ) +endmacro() + +################################################################################ +# Define Compiler flags (must be after main target defined) +################################################################################ +macro(cosm_hal_configure_buildflags) + if ("${COSM_HAL_TARGET}" MATCHES "argos-footbot") + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_FOOTBOT) + elseif("${COSM_HAL_TARGET}" MATCHES "argos-eepuck3d") + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_EEPUCK3D) + elseif("${COSM_HAL_TARGET}" MATCHES "argos-pipuck") + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_PIPUCK) + elseif("${COSM_HAL_TARGET}" MATCHES "argos-drone") + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_DRONE) + elseif("${COSM_HAL_TARGET}" MATCHES "ros-eturtlebot3") + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_HAL_TARGET=COSM_HAL_TARGET_ROS_ETURTLEBOT3) + endif() + + # Add definitions for each sensor the HAL target supports + foreach(SENSOR ${COSM_HAL_TARGET_SENSOR_SUITE}) + if (${SENSOR}) + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + ${SENSOR}) + endif() + endforeach() + + # Add definitions for each actuator the HAL target supports + foreach(ACTUATOR ${COSM_HAL_TARGET_ACTUATOR_SUITE}) + if (${ACTUATOR}) + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + ${ACTUATOR}) + endif() + endforeach() + + if (${COSM_HAL_TARGET_OPERATES_IN_Q3D}) + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_HAL_TARGET_OPERATES_IN_Q3D) + endif() + if (${COSM_HAL_TARGET_OPERATES_IN_3D}) + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_HAL_TARGET_OPERATES_IN_3D) + endif() +endmacro() diff --git a/cmake/pal.cmake b/cmake/pal.cmake new file mode 100644 index 00000000..9a10bdc0 --- /dev/null +++ b/cmake/pal.cmake @@ -0,0 +1,48 @@ +# +# Copyright 2022 John Harwell, All rights reserved. +# +# SPDX-License-Identifier: MIT +# + +################################################################################ +# Define PAL Target +################################################################################ +macro(cosm_pal_configure_target) + if("${COSM_BUILD_FOR}" MATCHES "ARGOS") + set(COSM_PAL_TARGET "ARGOS") + +elseif("${COSM_BUILD_FOR}" MATCHES "ROS") + set(COSM_PAL_TARGET "ROS") + + if (NOT COSM_ROS_MD5_CURRENT STREQUAL COSM_ROS_MD5) + message("ROS Msg MD5 changed ${COSM_ROS_MD5} -> ${COSM_ROS_MD5_CURRENT}") + set(COSM_ROS_MD5 + ${LIBRA_GIT_REV} + CACHE INTERNAL "MD5 hash used for ROS message versioning") + endif() +endif() + +configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/src/pal/pal.cpp.in + ${CMAKE_CURRENT_BINARY_DIR}/src/pal/pal.cpp + @ONLY + ) + +list(APPEND cosm_components_SRC "${CMAKE_CURRENT_BINARY_DIR}/src/pal/pal.cpp") +endmacro() + +################################################################################ +# Define Compiler flags (must be after main target defined) +################################################################################ +macro(cosm_pal_configure_buildflags) + if("${COSM_PAL_TARGET}" MATCHES "ARGOS") + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_ENABLE_PAL_TARGET_ARGOS) + elseif("${COSM_PAL_TARGET}" MATCHES "ROS") + target_compile_definitions(${cosm_LIBRARY} + PUBLIC + COSM_ENABLE_PAL_TARGET_ROS) + endif() +endmacro() + diff --git a/cmake/project-local.cmake b/cmake/project-local.cmake index b9fe8d74..e72dd21f 100644 --- a/cmake/project-local.cmake +++ b/cmake/project-local.cmake @@ -1,15 +1,22 @@ ################################################################################ -# Build Environment Configuration Options # +# Build Environment Configuration ################################################################################ # We are might be linking with a shared library set(CMAKE_POSITION_INDEPENDENT_CODE ON) set(cosm_CHECK_LANGUAGE "CXX") +# Each conference tag=minor increment. Each minor feature added=patch increment. +set(PROJECT_VERSION_MAJOR 1) +set(PROJECT_VERSION_MINOR 2) +set(PROJECT_VERSION_PATCH 9) +set(cosm_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}") + if(NOT DEFINED COSM_BUILD_ENV) set(COSM_BUILD_ENV "DEVEL") endif() + if("${COSM_BUILD_ENV}" MATCHES "DEVEL" ) # Nothing to do for now elseif("${COSM_BUILD_ENV}" MATCHES "ROBOT" ) @@ -20,81 +27,32 @@ else() message(FATAL_ERROR "Build environment must be: [DEVEL,ROBOT,MSI]") endif() -################################################################################ -# HAL Configuration Options # -################################################################################ -if(NOT DEFINED COSM_BUILD_FOR) - set(COSM_BUILD_FOR "ARGOS_FOOTBOT") -endif() +libra_configure_version( + ${CMAKE_CURRENT_SOURCE_DIR}/src/version/version.cpp.in + ${CMAKE_CURRENT_BINARY_DIR}/src/version/version.cpp + cosm_components_SRC + message("${cosm_components_SRC}") + ) +# list(APPEND cosm_components_SRC "${CMAKE_CURRENT_BINARY_DIR}/src/version/version.cpp") -if("${COSM_BUILD_FOR}" MATCHES "ARGOS_FOOTBOT") - set(COSM_HAL_TARGET "argos-footbot") - set(COSM_ARGOS_ROBOT_TYPE "foot-bot") - set(COSM_ARGOS_ROBOT_NAME_PREFIX "fb") - set(COSM_ARGOS_CONTROLLER_XML_ID "fbc") - -elseif("${COSM_BUILD_FOR}" MATCHES "ARGOS_EEPUCK3D") - set(COSM_HAL_TARGET "argos-eepuck3D") - set(COSM_ARGOS_ROBOT_TYPE "e-puck") - set(COSM_ARGOS_ROBOT_NAME_PREFIX "ep") - set(COSM_ARGOS_CONTROLLER_XML_ID "epc") - -elseif("${COSM_BUILD_FOR}" MATCHES "ARGOS_PIPUCK") - set(COSM_HAL_TARGET "argos-pipuck") - set(COSM_ARGOS_ROBOT_TYPE "pipuck") - set(COSM_ARGOS_ROBOT_NAME_PREFIX "pp") - set(COSM_ARGOS_CONTROLLER_XML_ID "ppc") -elseif("${COSM_BUILD_FOR}" MATCHES "ROS_ETURTLEBOT3") - set(COSM_HAL_TARGET "ros-eturtlebot3") - set(COSM_ROS_ROBOT_TYPE "eturtlebot3") - set(COSM_ROS_ROBOT_NAME_PREFIX "etb3_") -else() - set(COSM_BUILD_TARGETS - ARGOS_FOOTBOT - ARGOS_EEPUCK3D - ARGOS_PIPUCK - ROS_ETURTLEBOT3 - ) - message(FATAL_ERROR "Build target must be one of ${COSM_BUILD_TARGETS}") -endif() +include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/hal.cmake) +include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/pal.cmake) +include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/argos.cmake) +include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/ros.cmake) +include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/cosm-config-summary.cmake) ################################################################################ -# PAL Configuration Options # +# HAL Configuration ################################################################################ -if("${COSM_BUILD_FOR}" MATCHES "ARGOS") - set(COSM_PAL_TARGET "ARGOS") - set(COSM_PAL_NATIVE_BUILD ON) - -elseif("${COSM_BUILD_FOR}" MATCHES "ROS") - set(COSM_PAL_TARGET "ROS") - if(NOT CMAKE_CROSSCOMPILING) - set(COSM_PAL_NATIVE_BUILD ON) - else() - set(COSM_PAL_NATIVE_BUILD OFF) - endif() - - execute_process(COMMAND git rev-parse HEAD - OUTPUT_VARIABLE COSM_ROS_MD5_CURRENT - OUTPUT_STRIP_TRAILING_WHITESPACE) +cosm_hal_configure_target() - if (NOT COSM_ROS_MD5_CURRENT STREQUAL COSM_ROS_MD5) - message("ROS Msg MD5 changed ${COSM_ROS_MD5} -> ${COSM_ROS_MD5_CURRENT}") - set(COSM_ROS_MD5 - 0 # temporarily to make stuff easier ${COSM_ROS_MD5_CURRENT} - CACHE INTERNAL "MD5 hash used for ROS message versioning") - endif() -endif() - -configure_file( - ${CMAKE_CURRENT_SOURCE_DIR}/src/pal/pal.cpp.in - ${CMAKE_CURRENT_BINARY_DIR}/src/pal/pal.cpp - @ONLY - ) - -list(APPEND cosm_components_SRC "${CMAKE_CURRENT_BINARY_DIR}/src/pal/pal.cpp") +################################################################################ +# PAL Configuration +################################################################################ +cosm_pal_configure_target() ################################################################################ -# Qt Configuration Options # +# Qt Configuration ################################################################################ # Conditionally compile/link Qt visualizations. @@ -106,7 +64,7 @@ list(APPEND cosm_components_SRC "${CMAKE_CURRENT_BINARY_DIR}/src/pal/pal.cpp") # nice with the Intel compiler. if (NOT DEFINED COSM_WITH_VIS) if ("${CMAKE_SYSTEM_PROCESSOR}" MATCHES "x86_64" AND - "${COSM_BUILD_FOR}" MATCHES "ARGOS" AND + "${COSM_BUILD_FOR}" MATCHES "ARGOS" AND NOT "${CMAKE_CXX_COMPILER_ID}" MATCHES "Intel") set(COSM_WITH_VIS ON) else() @@ -128,25 +86,40 @@ if (COSM_WITH_VIS) endif() ################################################################################ -# Components # +# Components ################################################################################ +string(CONCAT Q3D_bindings_regex + "src/kin2D|" + "src/controller/base_controller2D|" + "src/controller/base_controllerQ3D|" + "src/subsystem/saa_subsystemQ3D" + ) +string(CONCAT 3D_bindings_regex + "src/controller/base_controller3D|" + "src/subsystem/saa_subsystem3D" + ) + string(CONCAT common_regex "src/ds/config|" - "src/hal/subsystem|" "src/hal/sensors|" "src/hal/actuators|" - "src/kin2D|" + "src/kin/|" # trailing slash needed not to catch kin2D + "src/nav|" "src/pal/config|" "src/pal/base_swarm_manager|" - "src/controller|" "src/ta|" "src/init|" - "src/subsystem|" + "src/controller/base_controller.cpp|" + "src/controller/config|" + "src/subsystem/base_|" + "src/subsystem/config|" + "src/subsystem/perception|" "src/apf2D|" + "src/flocking|" "src/metrics" ) -component_register_as_src( +libra_component_register_as_src( cosm_common_SRC cosm "${cosm_SRC}" @@ -154,85 +127,20 @@ component_register_as_src( "(${common_regex})") if ("${COSM_BUILD_FOR}" MATCHES "ARGOS") - string(CONCAT argos_regex - "src/ds|" - "src/arena|" - "src/convergence|" - "src/foraging|" - "src/fsm|" - "src/hal/argos|" - "src/hal/sensors|" - "src/metrics|" - "src/oracle|" - "src/pal/argos|" - "src/repr|" - "src/spatial|" - "src/tv|" - "src/argos" - ) - component_register_as_src( - cosm_argos_SRC - cosm - "${cosm_SRC}" - argos - "(${argos_regex})") - - if(COSM_WITH_VIS) - component_register_as_src( - cosm_argos_vis_SRC - cosm - "${cosm_SRC}" - argos_vis - "src/argos/vis") - endif() + include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/argos.cmake) - # Root project (not used in find_package()) - if (NOT cosm_FIND_COMPONENTS) - set(cosm_FIND_COMPONENTS - common - argos - argos_vis - ) - endif() + cosm_argos_configure_components() elseif("${COSM_BUILD_FOR}" MATCHES "ROS") - string(CONCAT ros_regex - "src/ros|" - "src/hal/ros|" - "src/pal/ros|" - "src/fsm|" - "src/foraging/fsm|" - "src/kin2D|" - "src/foraging/metrics|" - "src/spatial/fsm|" - "src/spatial/metrics|" - "src/spatial/strategy|" - "src/repr/operations/block_pickup|" - "src/repr/base_block3D|" - "src/repr/config/xml" - ) - component_register_as_src( - cosm_ros_SRC - cosm - "${cosm_SRC}" - ros - "(${ros_regex})") - - # Root project (not used in find_package()) - if (NOT cosm_FIND_COMPONENTS) - set(cosm_FIND_COMPONENTS - common - ros - ) - endif() - + include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/ros.cmake) + cosm_ros_configure_components() endif() -requested_components_check(cosm) +libra_requested_components_check(cosm) ################################################################################ -# External Projects # +# External Projects ################################################################################ # RCPPSW find_package(rcppsw COMPONENTS REQUIRED @@ -274,7 +182,7 @@ endif() # irritating. ################################################################################ -# Libraries # +# Libraries ################################################################################ # Create the source for the SINGLE library to build by combining the # source of the selected components @@ -284,18 +192,6 @@ foreach(component ${cosm_FIND_COMPONENTS}) endif() endforeach() -# Configure version -execute_process(COMMAND git rev-list --count HEAD - OUTPUT_VARIABLE COSM_VERSION - OUTPUT_STRIP_TRAILING_WHITESPACE) - -configure_file( - ${CMAKE_CURRENT_SOURCE_DIR}/src/version.cpp.in - ${CMAKE_CURRENT_BINARY_DIR}/src/version.cpp - @ONLY - ) -list(APPEND cosm_components_SRC "${CMAKE_CURRENT_BINARY_DIR}/src/version.cpp") - # Define the COSM library set(cosm_LIBRARY ${target}-${COSM_HAL_TARGET}) @@ -315,6 +211,17 @@ set_target_properties(${cosm_LIBRARY} PROPERTIES OUTPUT_NAME ${cosm_LIBRARY_NAME} ) + +# Setting this results in TWO files being installed: the actual +# library with the version embedded, and a symlink to the actual +# library with the same name sans the embedded version (if COSM +# is built as a shared library). +set_target_properties(${cosm_LIBRARY} + PROPERTIES + VERSION ${cosm_VERSION} + SOVERSION ${cosm_VERSION} + ) + ######################################## # Include directories ######################################## @@ -360,7 +267,6 @@ if (${COSM_WITH_VIS}) OpenGL::GL ) endif() - if ("${COSM_BUILD_FOR}" MATCHES "ARGOS") target_link_directories(${cosm_LIBRARY} PUBLIC @@ -369,6 +275,7 @@ if ("${COSM_BUILD_FOR}" MATCHES "ARGOS") argos3core_simulator argos3plugin_simulator_footbot argos3plugin_simulator_epuck + argos3plugin_simulator_drone argos3plugin_simulator_entities argos3plugin_simulator_dynamics2d argos3plugin_simulator_genericrobot @@ -383,56 +290,41 @@ target_link_options(${cosm_LIBRARY} PRIVATE -Wl,--no-undefined) ######################################## # Compile Options/Definitions ######################################## -if ("${COSM_BUILD_FOR}" MATCHES "ROS") - target_compile_options(${cosm_LIBRARY} - PUBLIC - -Wno-psabi) -endif() - -if ("${COSM_HAL_TARGET}" MATCHES "argos-footbot") - target_compile_definitions(${cosm_LIBRARY} - PUBLIC - COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_FOOTBOT) -elseif("${COSM_HAL_TARGET}" MATCHES "argos-eepuck3d") - target_compile_definitions(${cosm_LIBRARY} - PUBLIC - COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_EEPUCK3D) -elseif("${COSM_HAL_TARGET}" MATCHES "argos-pipuck") - target_compile_definitions(${cosm_LIBRARY} - PUBLIC - COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_PIPUCK) -elseif("${COSM_HAL_TARGET}" MATCHES "ros-eturtlebot3") - target_compile_definitions(${cosm_LIBRARY} - PUBLIC - COSM_HAL_TARGET=COSM_HAL_TARGET_ROS_ETURTLEBOT3) -endif() - -if("${COSM_PAL_TARGET}" MATCHES "ARGOS") - target_compile_definitions(${cosm_LIBRARY} - PUBLIC - COSM_ENABLE_PAL_TARGET_ARGOS) -elseif("${COSM_PAL_TARGET}" MATCHES "ROS") - target_compile_definitions(${cosm_LIBRARY} - PUBLIC - COSM_ENABLE_PAL_TARGET_ROS) -endif() +cosm_hal_configure_buildflags() +cosm_pal_configure_buildflags() ################################################################################ -# Installation # +# Installation and Deployment ################################################################################ -configure_exports_as(${cosm_LIBRARY} ${CMAKE_INSTALL_PREFIX}) +libra_configure_exports_as(${cosm_LIBRARY} ${CMAKE_INSTALL_PREFIX}) + +# Install COSM +libra_register_target_for_install(${cosm_LIBRARY} ${CMAKE_INSTALL_PREFIX}) +libra_register_headers_for_install(include/cosm ${CMAKE_INSTALL_PREFIX}) -# Install cosm -register_target_for_install(${cosm_LIBRARY} ${CMAKE_INSTALL_PREFIX}) -register_headers_for_install(include/cosm ${CMAKE_INSTALL_PREFIX}) -register_extra_configs_for_install(${cosm_LIBRARY} - ${CMAKE_CURRENT_SOURCE_DIR}/cmake/cosm-config-summary.cmake +file(GLOB COSM_CMAKE_FILES "${CMAKE_CURRENT_SOURCE_DIR}/cmake/*.cmake") +libra_register_extra_configs_for_install(${cosm_LIBRARY} + "${COSM_CMAKE_FILES}" ${CMAKE_INSTALL_PREFIX}) +# Deploy COSM +set(CPACK_SET_DESTDIR YES) +set(CPACK_PACKAGE_FILE_NAME + ${cosm_LIBRARY}-${cosm_VERSION}-${CMAKE_SYSTEM_PROCESSOR}) +libra_configure_cpack( + "DEB;TGZ" + + "Core Swarm (COSM) is a collection of non application, method, or controller +specific software components that can be reused across multiple +Multi-Agent System (MAS) projects (i.e., generic in the context of +MAS, but maybe not more broadly). " + + "John Harwell" + "https://jharwell.github.io/cosm" + "John Harwell ") + ################################################################################ -# Status # +# Status ################################################################################ -include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/cosm-config-summary.cmake) libra_config_summary() - cosm_config_summary() diff --git a/cmake/ros.cmake b/cmake/ros.cmake new file mode 100644 index 00000000..11e4f87a --- /dev/null +++ b/cmake/ros.cmake @@ -0,0 +1,46 @@ +# +# Copyright 2022 John Harwell, All rights reserved. +# +# SPDX-License-Identifier: MIT +# +macro(cosm_ros_configure_components) + string(CONCAT ros_regex + "src/ros|" + "src/hal/ros|" + "src/pal/ros|" + "src/fsm|" + "src/foraging/fsm|" + "src/kin2D|" + "src/foraging/metrics|" + "src/spatial/fsm|" + "src/spatial/metrics|" + "src/spatial/strategy|" + "src/repr/operations/block_pickup|" + "src/repr/base_block3D|" + "src/repr/config/xml" + ) + + if(${COSM_HAL_TARGET_OPERATES_IN_Q3D}) + string(CONCAT ros_regex "${ros_regex} | ${Q3D_bindings_regex}") + endif() + + if(${COSM_HAL_TARGET_OPERATES_IN_3D}) + string(CONCAT ros_regex "${ros_regex} | ${3D_bindings_regex}") + endif() + + libra_component_register_as_src( + cosm_ros_SRC + cosm + "${cosm_SRC}" + ros + "(${ros_regex})") + + # Root project (not used in find_package()) + if (NOT cosm_FIND_COMPONENTS) + set(cosm_FIND_COMPONENTS + common + ros + ) + endif() + +endmacro() diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index f5e2aba3..be5dd3d5 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.8.11 +# Doxyfile 1.9.1 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -17,11 +17,11 @@ # Project related configuration options #--------------------------------------------------------------------------- -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all text -# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv -# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv -# for the list of possible encodings. +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 @@ -32,13 +32,13 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "COSM" +PROJECT_NAME = COSM # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = +PROJECT_NUMBER = @PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@ # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -60,7 +60,6 @@ PROJECT_LOGO = OUTPUT_DIRECTORY = @CMAKE_BINARY_DIR@/docs/cosm - # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and # will distribute the generated files over these directories. Enabling this @@ -94,6 +93,14 @@ ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English +# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all generated output in the proper direction. +# Possible values are: None, LTR, RTL and Context. +# The default value is: None. + +OUTPUT_TEXT_DIRECTION = None + # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. @@ -153,7 +160,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = ../include # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -180,6 +187,16 @@ SHORT_NAMES = NO JAVADOC_AUTOBRIEF = NO +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus @@ -200,6 +217,14 @@ QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. @@ -227,16 +252,15 @@ TAB_SIZE = 4 # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading # "Side Effects:". You can put \n's in the value part of an alias to insert -# newlines. +# newlines (in the resulting output). You can put ^^ in the value part of an +# alias to insert a newline as if a physical newline was in the original file. +# When you need a literal { or } or , in the value part of an alias you have to +# escape them by means of a backslash (\), this can lead to conflicts with the +# commands \{ and \} for these it is advised to use the version @{ and @} or use +# a double escape (\\{ and \\}) ALIASES = -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -265,28 +289,40 @@ OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: -# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: -# Fortran. In the later case the parser tries to guess whether the code is fixed -# or free formatted code, this is the default for Fortran type files), VHDL. For -# instance to make doxygen treat .inc files as Fortran files (default is PHP), -# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, +# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. +# the files are not read by doxygen. When specifying no_extension you should add +# * to the FILE_PATTERNS. +# +# Note see also the list of default file extension mappings. EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable -# documentation. See http://daringfireball.net/projects/markdown/ for details. +# documentation. See https://daringfireball.net/projects/markdown/ for details. # The output of markdown processing is further processed by doxygen, so you can # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. @@ -294,6 +330,15 @@ EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 5. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 5 + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or @@ -319,7 +364,7 @@ BUILTIN_STL_SUPPORT = YES CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen # will parse them like normal C++ but will assume all classes use public instead # of private inheritance when no explicit protection keyword is present. # The default value is: NO. @@ -405,6 +450,19 @@ TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 0 +# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which efficively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -417,7 +475,7 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = YES +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -425,6 +483,12 @@ EXTRACT_ALL = YES EXTRACT_PRIVATE = NO +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. @@ -462,6 +526,13 @@ EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation @@ -479,8 +550,8 @@ HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO, these declarations will be -# included in the documentation. +# declarations. If set to NO, these declarations will be included in the +# documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO @@ -499,11 +570,18 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES, upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. +# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# able to match the capabilities of the underlying filesystem. In case the +# filesystem is case sensitive (i.e. it supports files in the same directory +# whose names only differ in casing), the option must be set to YES to properly +# deal with such files in case they appear in the input. For filesystems that +# are not case sensitive the option should be be set to NO to properly deal with +# output files written for symbols that only differ in casing, such as for two +# classes, one named CLASS and the other named Class, and to also support +# references to files without having to specify the exact matching casing. On +# Windows (including Cygwin) and MacOS, users should typically set this option +# to NO, whereas on Linux or other Unix flavors it should typically be set to +# YES. # The default value is: system dependent. CASE_SENSE_NAMES = YES @@ -690,12 +768,14 @@ LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. -CITE_BIB_FILES = +CITE_BIB_FILES = /home/jharwell/texmf/bibtex/bib/harwell.bib \ + /home/jharwell/texmf/bibtex/bib/platforms-and-tools.bib \ + /home/jharwell/texmf/bibtex/bib/task-alloc.bib #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages @@ -722,7 +802,7 @@ WARNINGS = YES # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters @@ -735,13 +815,17 @@ WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return # value. If set to NO, doxygen will only warn about wrong or incomplete -# parameter documentation, but not about the absence of documentation. +# parameter documentation, but not about the absence of documentation. If +# EXTRACT_ALL is set to YES then this flag will automatically be disabled. # The default value is: NO. WARN_NO_PARAMDOC = YES # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when -# a warning is encountered. +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. # The default value is: NO. WARN_AS_ERROR = NO @@ -772,13 +856,13 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = @CMAKE_CURRENT_SOURCE_DIR@/include/cosm +INPUT = @CMAKE_CURRENT_SOURCE_DIR@/include/cosm # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: http://www.gnu.org/software/libiconv) for the list of -# possible encodings. +# documentation (see: +# https://www.gnu.org/software/libiconv/) for the list of possible encodings. # The default value is: UTF-8. INPUT_ENCODING = UTF-8 @@ -791,11 +875,15 @@ INPUT_ENCODING = UTF-8 # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # +# Note the list of default checked file patterns might differ from the list of +# default file extension mappings. +# # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, -# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl, -# *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js. +# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), +# *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, *.vhdl, +# *.ucf, *.qsf and *.ice. FILE_PATTERNS = @@ -886,7 +974,7 @@ IMAGE_PATH = # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. -INPUT_FILTER = +INPUT_FILTER = ../scripts/doxy_prepare.sh # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern # basis. Doxygen will compare the file name with each pattern and apply the @@ -950,7 +1038,7 @@ INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented -# function all documented functions referencing it will be listed. +# entity all documented functions referencing it will be listed. # The default value is: NO. REFERENCED_BY_RELATION = NO @@ -982,12 +1070,12 @@ SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system -# (see http://www.gnu.org/software/global/global.html). You will need version +# (see https://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: # - Install the latest version of global -# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file # - Make sure the INPUT points to the root of the source tree # - Run doxygen as normal # @@ -1010,16 +1098,22 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES # If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the -# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the -# cost of reduced performance. This can be particularly helpful with template -# rich C++ code for which doxygen's built-in parser lacks the necessary type -# information. +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. # Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse-libclang=ON option for CMake. +# generated with the -Duse_libclang=ON option for CMake. # The default value is: NO. CLANG_ASSISTED_PARSING = NO +# If clang assisted parsing is enabled and the CLANG_ADD_INC_PATHS tag is set to +# YES then doxygen will add the directory of each input to the include path. +# The default value is: YES. + +CLANG_ADD_INC_PATHS = YES + # If clang assisted parsing is enabled you can provide the compiler with command # line options that you would normally use when invoking the compiler. Note that # the include paths will already be set by doxygen for the files and directories @@ -1028,6 +1122,19 @@ CLANG_ASSISTED_PARSING = NO CLANG_OPTIONS = +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1039,13 +1146,6 @@ CLANG_OPTIONS = ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1061,7 +1161,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = NO +GENERATE_HTML = YES # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1146,7 +1246,7 @@ HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see -# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. @@ -1182,6 +1282,17 @@ HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = NO +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. @@ -1205,13 +1316,14 @@ HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: http://developer.apple.com/tools/xcode/), introduced with -# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a -# Makefile in the HTML output directory. Running make will produce the docset in -# that directory and running make install will install the docset in +# environment (see: +# https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To +# create a documentation set, doxygen will generate a Makefile in the HTML +# output directory. Running make will produce the docset in that directory and +# running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at -# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1250,8 +1362,8 @@ DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on -# Windows. +# (see: +# https://www.microsoft.com/en-us/download/details.aspx?id=21138) on Windows. # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML @@ -1281,7 +1393,7 @@ CHM_FILE = HHC_LOCATION = # The GENERATE_CHI flag controls if a separate .chi index file is generated -# (YES) or that it should be included in the master .chm file (NO). +# (YES) or that it should be included in the main .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. @@ -1326,7 +1438,8 @@ QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace -# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1334,8 +1447,8 @@ QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- -# folders). +# Folders (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1343,30 +1456,30 @@ QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = -# The QHG_LOCATION tag can be used to specify the location of Qt's -# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the -# generated .qhp file. +# The QHG_LOCATION tag can be used to specify the location (absolute path +# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to +# run qhelpgenerator on the generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = @@ -1417,7 +1530,7 @@ DISABLE_INDEX = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. @@ -1443,6 +1556,17 @@ TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML @@ -1452,7 +1576,7 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images # generated for formulas are transparent PNGs. Transparent PNGs are not # supported properly for IE 6.0, but are supported on all modern browsers. # @@ -1463,8 +1587,14 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# http://www.mathjax.org) which uses client side Javascript for the rendering +# https://www.mathjax.org) which uses client side JavaScript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path @@ -1476,7 +1606,7 @@ USE_MATHJAX = NO # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/latest/output.html) for more details. +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. # Possible values are: HTML-CSS (which is slower, but has the best # compatibility), NativeMML (i.e. MathML) and SVG. # The default value is: HTML-CSS. @@ -1491,8 +1621,8 @@ MATHJAX_FORMAT = HTML-CSS # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of -# MathJax from http://www.mathjax.org before deployment. -# The default value is: http://cdn.mathjax.org/mathjax/latest. +# MathJax from https://www.mathjax.org before deployment. +# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest @@ -1506,7 +1636,8 @@ MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site -# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1534,7 +1665,7 @@ MATHJAX_CODEFILE = SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a web server instead of a web client using Javascript. There +# implemented using a web server instead of a web client using JavaScript. There # are two flavors of web server based searching depending on the EXTERNAL_SEARCH # setting. When disabled, doxygen will generate a PHP script for searching and # an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing @@ -1553,7 +1684,8 @@ SERVER_BASED_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). +# Xapian (see: +# https://xapian.org/). # # See the section "External Indexing and Searching" for details. # The default value is: NO. @@ -1566,8 +1698,9 @@ EXTERNAL_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). See the section "External Indexing and -# Searching" for details. +# Xapian (see: +# https://xapian.org/). See the section "External Indexing and Searching" for +# details. # This tag requires that the tag SEARCHENGINE is set to YES. SEARCHENGINE_URL = @@ -1618,21 +1751,35 @@ LATEX_OUTPUT = latex # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be # invoked. # -# Note that when enabling USE_PDFLATEX this option is only used for generating -# bitmaps for formulas in the HTML output, but not in the Makefile that is -# written to the output directory. -# The default file is: latex. +# Note that when not enabling USE_PDFLATEX the default is latex when enabling +# USE_PDFLATEX the default is pdflatex and when in the later case latex is +# chosen this is overwritten by pdflatex. For specific output languages the +# default can have been set differently, this depends on the implementation of +# the output language. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_CMD_NAME = latex # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate # index for LaTeX. +# Note: This tag is used in the Makefile / make.bat. +# See also: LATEX_MAKEINDEX_CMD for the part in the generated output file +# (.tex). # The default file is: makeindex. # This tag requires that the tag GENERATE_LATEX is set to YES. MAKEINDEX_CMD_NAME = makeindex +# The LATEX_MAKEINDEX_CMD tag can be used to specify the command name to +# generate index for LaTeX. In case there is no backslash (\) as first character +# it will be automatically added in the LaTeX code. +# Note: This tag is used in the generated output file (.tex). +# See also: MAKEINDEX_CMD_NAME for the part in the Makefile / make.bat. +# The default value is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_MAKEINDEX_CMD = makeindex + # If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX # documents. This may be useful for small projects and may help to save some # trees in general. @@ -1717,9 +1864,11 @@ LATEX_EXTRA_FILES = PDF_HYPERLINKS = YES -# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate -# the PDF file directly from the LaTeX files. Set this option to YES, to get a -# higher quality PDF documentation. +# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as +# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX +# files. Set this option to YES, to get a higher quality PDF documentation. +# +# See also section LATEX_CMD_NAME for selecting the engine. # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1753,7 +1902,7 @@ LATEX_SOURCE_CODE = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See -# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. # The default value is: plain. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1767,6 +1916,14 @@ LATEX_BIB_STYLE = plain LATEX_TIMESTAMP = NO +# The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) +# path from which the emoji images will be read. If a relative path is entered, +# it will be relative to the LATEX_OUTPUT directory. If left blank the +# LATEX_OUTPUT directory will be used. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EMOJI_DIRECTORY = + #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- @@ -1806,9 +1963,9 @@ COMPACT_RTF = NO RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's config -# file, i.e. a series of assignments. You only have to provide replacements, -# missing definitions are set to their default value. +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# configuration file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. # # See also section "Doxygen usage" for information on how to generate the # default style sheet that doxygen normally uses. @@ -1817,8 +1974,8 @@ RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = # Set optional variables used in the generation of an RTF document. Syntax is -# similar to doxygen's config file. A template extensions file can be generated -# using doxygen -e rtf extensionFile. +# similar to doxygen's configuration file. A template extensions file can be +# generated using doxygen -e rtf extensionFile. # This tag requires that the tag GENERATE_RTF is set to YES. RTF_EXTENSIONS_FILE = @@ -1904,6 +2061,13 @@ XML_OUTPUT = xml XML_PROGRAMLISTING = YES +# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include +# namespace members in file scope as well, matching the HTML output. +# The default value is: NO. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_NS_MEMB_FILE_SCOPE = NO + #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- @@ -1936,9 +2100,9 @@ DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sf.net) file that captures the -# structure of the code including all documentation. Note that this feature is -# still experimental and incomplete at the moment. +# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# the structure of the code including all documentation. Note that this feature +# is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO @@ -2038,7 +2202,34 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = +PREDEFINED = RCPPSW_PURE= \ + DOXYGEN_DOCUMENTATION_BUILD=1 \ + RCPPSW_COLD= \ + RCPPSW_DEAD= \ + RCPPSW_UNUSED= \ + __cplusplus \ + RCPPSW_NODISCARD= \ + RCPPSW_LIB_INIT= \ + ROS_DECLARE_ALLINONE_SERIALIZER= \ + COSM_ENABLE_PAL_TARGET_ARGOS \ + COSM_ENABLE_PAL_TARGET_ROS \ + COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_FOOTBOT \ + COSM_HAL_TARGET=COSM_HAL_TARGET_ARGOS_DRONE \ + COSM_HAL_TARGET_HAS_IR_SENSOR \ + COSM_HAL_TARGET_HAS_LIDAR_SENSOR \ + COSM_HAL_TARGET_HAS_CAMERA_BLOBS_SENSOR \ + COSM_HAL_TARGET_HAS_LIGHT_SENSOR \ + COSM_HAL_TARGET_HAS_ENV_SENSOR \ + COSM_HAL_TARGET_HAS_BATTERY_SENSOR \ + COSM_HAL_TARGET_HAS_GROUND_SENSOR \ + COSM_HAL_TARGET_HAS_QUADROTOR_SENSOR \ + COSM_HAL_TARGET_HAS_PROX_SENSOR \ + COSM_HAL_TARGET_HAS_WIFI_SENSOR \ + COSM_HAL_TARGET_HAS_DIFF_DRIVE_SENSOR \ + COSM_HAL_TARGET_HAS_DIFF_DRIVE_ACTUATOR \ + COSM_HAL_TARGET_HAS_WIFI_ACTUATOR \ + COSM_HAL_TARGET_HAS_QUADROTOR_ACTUATOR + # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2076,7 +2267,7 @@ SKIP_FUNCTION_MACROS = NO # the path). If a tag file is not located in the directory in which doxygen is # run, you must also specify the path to the tagfile here. -TAGFILES = @CMAKE_BINARY_DIR@/docs/rcsw/RCSW.tag=@CMAKE_BINARY_DIR@/docs/rcsw/html\ +TAGFILES = @CMAKE_BINARY_DIR@/docs/rcsw/RCSW.tag=@CMAKE_BINARY_DIR@/docs/rcsw/html \ @CMAKE_BINARY_DIR@/docs/rcppsw/RCPPSW.tag=@CMAKE_BINARY_DIR@/docs/rcppsw/html # When a file name is specified after GENERATE_TAGFILE, doxygen will create a @@ -2106,12 +2297,6 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -PERL_PATH = /usr/bin/perl - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- @@ -2125,15 +2310,6 @@ PERL_PATH = /usr/bin/perl CLASS_DIAGRAMS = YES -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. @@ -2231,10 +2407,32 @@ UML_LOOK = YES # but if the number exceeds 15, the total amount of fields shown is limited to # 10. # Minimum value: 0, maximum value: 100, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. +# This tag requires that the tag UML_LOOK is set to YES. UML_LIMIT_NUM_FIELDS = 10 +# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS +# tag is set to YES, doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# will not generate fields with class member information in the UML graphs. The +# class diagrams will look similar to the default class diagrams but using UML +# notation for the relationships. +# Possible values are: NO, YES and NONE. +# The default value is: NO. +# This tag requires that the tag UML_LOOK is set to YES. + +DOT_UML_DETAILS = NO + +# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters +# to display on a single line. If the actual line length exceeds this threshold +# significantly it will wrapped across multiple lines. Some heuristics are apply +# to avoid ugly line breaks. +# Minimum value: 0, maximum value: 1000, default value: 17. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_WRAP_THRESHOLD = 17 + # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their # instances. @@ -2363,6 +2561,11 @@ DIAFILE_DIRS = PLANTUML_JAR_PATH = +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + # When using plantuml, the specified paths are searched for files specified by # the !include statement in a plantuml block. @@ -2421,9 +2624,11 @@ DOT_MULTI_TARGETS = NO GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate # files that are used to generate the various graphs. +# +# Note: This setting is not only used for dot files but also for msc and +# plantuml temporary files. # The default value is: YES. -# This tag requires that the tag HAVE_DOT is set to YES. DOT_CLEANUP = YES diff --git a/docs/Makefile b/docs/Makefile index cfa18c63..a58373eb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,3 +18,6 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +clean: + rm -rf _api/ + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/build.rst b/docs/build.rst deleted file mode 100644 index 832209ff..00000000 --- a/docs/build.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. SPDX-License-Identifier: LGPL-2.0-or-later - -.. _ln-build: - -Building COSM -================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - -CMake Variables ---------------- - -COSM requires the following CMake variables to be defined in order to -successfully build. - -- ``COSM_BUILD_FOR`` - The target platform that COSM will be built for. Must be - one of [ ``MSI``, ``ARGOS_FOOTBOT``, ``ARGOS_EEPUCK3D`` ]. - -- ``COSM_DEPS_PREFIX`` - Prefix for where ARGoS and other dependencies in the - parent project have been installed. - -- ``COSM_BUILD_ENV`` - The target build environment that COSM will be built - in. Must be one of [ ``LOCAL``, ``MSI`` ]. - -- ``COSM_HAL_TARGET`` - Specify the Hardware Abstraction Layer (HAL) - target. Must be one of: [ ``argos-footbot``, ``lego-ev3`` ]. - -- ``COSM_PAL_ARGOS_ROBOT_TYPE`` - The name of the type of robots within the swarm - from the POV of ARGoS. Must match the type of robots in the XML input files - fed to ARGoS!. - -- ``COSM_PAL_ARGOS_ROBOT_NAME_PREFIX`` - The prefix that all robot names have within - ARGoS. Must match the robot name prefix in the XML input files fed to ARGoS!. - -- ``COSM_PAL_ARGOS_CONTROLLER_XML_ID`` - The unique name attached to the controller - of the desired type in the XML input file to the the actual controller class - in C++ code. diff --git a/docs/conf.py b/docs/conf.py index 0cc7c742..13929dac 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,10 +19,98 @@ # import os import sys +import textwrap +import pathlib import subprocess + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# sys.path.insert(0, os.path.abspath('..')) -sys.path.insert(0, os.path.abspath('_ext')) +# -- Project information ----------------------------------------------------- + +project = 'COSM' +copyright = '2022, John Harwell' +author = 'John Harwell' + +version_major = subprocess.run(("grep " + "PROJECT_VERSION_MAJOR " + "../cmake/project-local.cmake |" + "grep -Eo [0-9]+"), + shell=True, + check=True, + stdout=subprocess.PIPE).stdout.decode().strip('\n') +version_minor = subprocess.run(("grep " + "PROJECT_VERSION_MINOR " + "../cmake/project-local.cmake |" + "grep -Eo [0-9]+"), + shell=True, + check=True, + stdout=subprocess.PIPE).stdout.decode().strip('\n') +version_patch = subprocess.run(("grep " + "PROJECT_VERSION_PATCH " + "../cmake/project-local.cmake |" + "grep -Eo [0-9]+"), + shell=True, + check=True, + stdout=subprocess.PIPE).stdout.decode().strip('\n') + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = f'{version_major}.{version_minor}.{version_patch}' + +# The full version, including alpha/beta/rc tags. +stdout = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], + stdout=subprocess.PIPE, + check=True).stdout +git_branch = stdout.decode("ascii").strip('\n') + +if git_branch == 'devel': + version = f'{version}.beta' + +cosm_root = pathlib.Path(os.path.abspath("..")) +breathe_projects = { + "COSM": str(cosm_root / "build/docs/cosm/xml") +} +breathe_default_project = "COSM" +paths = [] +for root, subs, files in os.walk(str(cosm_root / "include/")): + for f in files: + paths.append(os.path.abspath(os.path.join(root, f))) + +breathe_projects_source = {"COSM": (str(cosm_root / "include"), paths)} + + +exhale_args = { + "containmentFolder": "./_api", + "rootFileName": "api.rst", + "rootFileTitle": "COSM API", + "afterTitleDescription": textwrap.dedent(''' + .. note:: + + Some functions declared+defined within classes using variadic macros + might not be included, due to limits in the doxygen+breathe+exhale + toolchain. Such functions are usually found in classes which wrap or + decorate large portions of a base class functionality/member variable + functionality. '''), + + "doxygenStripFromPath": "../include", + "verboseBuild": False, + 'exhaleExecutesDoxygen': False, + "createTreeView": True +} + +doxylink = { + 'cosm': (str(cosm_root / 'build/docs/cosm/COSM.tag'), + str(cosm_root / 'build/docs/cosm/html/')) +} # -- General configuration ------------------------------------------------ @@ -38,9 +126,11 @@ 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', - 'xref', + 'sphinxcontrib.doxylink', 'breathe', - 'sphinx_rtd_theme'] + 'exhale', + 'sphinx_rtd_theme', + 'sphinx_last_updated_by_git'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -54,20 +144,6 @@ # The master toctree document. master_doc = 'index' -# General information about the project. -project = 'COSM' -copyright = '2019, John Harwell' -author = 'John Harwell' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '' -# The full version, including alpha/beta/rc tags. -release = '' - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -87,50 +163,7 @@ todo_include_todos = True -def get_subtree(ns: str): - paths = [] - for root, subs, files in os.walk(os.path.join('../include/rcppsw', ns)): - for f in files: - paths.append(os.path.abspath(os.path.join(root, f))) - return paths - - -project_keys = ['arena', - 'controller', - 'convergence', - 'ds', - 'foraging', - 'fsm', - 'hal', - 'interactors', - 'kin', - 'kin2D', - 'metrics', - 'oracle', - 'pal', - 'repr', - 'robots', - 'apf2D', - 'subsystem', - 'ta', - 'tv', - 'vis'] - -breathe_projects = {'cosm': '../build/docs/cosm/xml'} -breathe_projects_source = {'cosm': ('../include/cosm', get_subtree(''))} -breathe_default_project = "cosm" -breathe_default_members = ('members',) - -for k in project_keys: - breathe_projects.update({k: "../build/docs/cosm/xml"}) - breathe_projects_source.update({k: ('../include/cosm/' + k, get_subtree(k))}) - xref_links = { - "COSM": ("COSM", "https://swarm-robotics-cosm.readthedocs.io"), - "SILICON": ("SILICON", "https://swarm-robotics-silicon.readthedocs.io"), - "SIERRA": ("SIERRA", "https://swarm-robotics-sierra.readthedocs.io"), - "LIBRA": ("LIBRA", "https://swarm-robotics-libra.readthedocs.io"), - "Auer2002": ("Auer2002", "https://link.springer.com/article/10.1023/A:1013689704352"), "Pini2011": ("Pini2011", "https://link.springer.com/article/10.1007/s11721-011-0060-1"), "Brutschy2014": ("Brutschy2014", "https://link.springer.com/article/10.1007/s10458-012-9212-y"), @@ -170,83 +203,10 @@ def get_subtree(ns: str): } -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'COSMdoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'COSM.tex', 'COSM Documentation', - 'John Harwell', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'cosm', 'COSM Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'COSM', 'COSM Documentation', - author, 'COSM', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for Epub output ---------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = copyright - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - - # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +intersphinx_mapping = {'libra': ('https://jharwell.github.io/libra/', + None), + 'rcsw': ('https://jharwell.github.io/rcsw/', + None), + 'rcppsw': ('https://jharwell.github.io/rcppsw/', + None)} diff --git a/docs/config/index.rst b/docs/config/index.rst deleted file mode 100644 index 80be25d2..00000000 --- a/docs/config/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. SPDX-License-Identifier: LGPL-2.0-or-later - -.. _ln-xml-config: - -XML Configuration -================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - controllers.rst - swarm-manager.rst - -XML Conventions ---------------- - -- Multiple choices for an XML attribute value are separated by a ``|`` in the - example XML. - -- XML attributes that should be floating point are specified as ``FLOAT`` in the - example XML (acceptable range, if applicable, is documented for each - individual attribute). - -- XML attributes that should be integers are specified as ``INTEGER`` in the - example XML (acceptable range, if applicable, is documented for each - individual attribute). diff --git a/docs/index.rst b/docs/index.rst index ddb1d644..2c1bccec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,36 @@ -.. SPDX-License-Identifier: LGPL-2.0-or-later +.. SPDX-License-Identifier: MIT +================================ Welcome to COSM's documentation! ================================ +Overview +======== + +Core Swarm (COSM) is a middleware-esque library providing: + +- A :ref:`ln-cosm-support-pal`: A common API to different platforms (ARgoS, ROS, + etc) which client applications can write to. + +- A see :ref:`ln-cosm-support-hal`: A common API to different agent/robot types + which client applications to write to. + +- A collection of reusable algorithms and scaffolding to maximize reuse across + MAS projects and reduce development time (see :ref:`ln-cosm-modules` for a + very brief overview). + .. toctree:: :maxdepth: 2 - :caption: Contents: - - config/index.rst - build.rst + :caption: Getting Started - api/index.rst + src/modules.rst + src/support.rst + src/setup/index.rst + src/usage/index.rst + _api/api.rst -Other Projects (in descending probability of interest) ------------------------------------------------------- +.. toctree:: + :maxdepth: 2 + :caption: Extending COSM -- `SILICON `_ -- `FORDYCA `_ -- `SIERRA `_ -- `RCPPSW `_ -- `RCSW `_ + src/extend/hal.rst diff --git a/docs/src/extend/hal.rst b/docs/src/extend/hal.rst new file mode 100644 index 00000000..beecd870 --- /dev/null +++ b/docs/src/extend/hal.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: MIT + +.. _ln-cosm-extend-hal: + +================================== +Adding A New Agent Type To The HAL +================================== + +Below is a ROUGH outline of how to add a new agent type to an already existing +platform. In all likelihood, the steps below will be insufficient, so please +update these docs as you go. + +#. Define your agent in ``cmake/hal.cmake``: + + - Define members of ``COSM_HAL_TARGET_SENSOR_SUITE`` and + ``COSM_HAL_TARGET_ACTUATOR_SUITE`` as appropriate. + + - Define whether the agent operates in 2D or 3D with + ``COSM_HAL_TARGET_OPERATES_IN_3D`` or + ``COSM_HAL_TARGET_OPERATES_IN_Q3D``. There is not "operates in 2D" mode, + because all agents sense in 3D if the underlying PAL platform supports + in. If it doesn't, then the Z component is just zeroed everywhere. + +#. Add a new ``#define`` in ``cosm/hal/hal.hpp``, following the convention of:: + + #define COSM_HAL_TARGET__ + +#. For each sensor that your agent is equipped with, add an appropriate sensor + in the HAL if one does not already exist under + ``cosm/hal//sensors``. If one already exist, add your agent type to + the set of agent types which define that sensor/actuator. + + .. IMPORTANT:: Each agent type MUST define the following sensors even if they + are actually not present on the agent: + + - :cosm:`cosm::hal::sensors::env_sensor` + - :cosm:`cosm::hal::sensors::light_sensor` + - :cosm:`cosm::hal::sensors::proximity_sensor` + - :cosm:`cosm::hal::sensors::odometry_sensor` + + If the agent doesn't have the sensor, then + :cosm:`cosm::hal::sensors::stub_sensor` can be used. + + There is a lot of stuff under ``spatial/`` which depends one or more of these + sensors, and requiring all agents "support" this set of sensors seemed like + the lesser of two evils. Other options considered, but rejected for the + moment: + + - Put ``#if defined`` guards around sensor usage causing the errors. This + violates the general ethos that all such guards and other trickery should + be confined to the HAL. + + This decision may be revisited in the future. + +#. For each actuator that your agent is equipped with, add an appropriate actuator + in the HAL if one does not already exist under + ``cosm/hal//sensors``. If one already exist, add your agent type to + the set of agent types which define that sensor/actuator. + + .. IMPORTANT:: Each agent type MUST define the following actuators: + + - :cosm:`cosm::hal::actuators::locomation_actuator` + +#. Under ``cosm/hal//subsystem/robot_available_sensors.hpp`` add an + entry for your agent to define the sensors that it has. If you don't define + the sensors here, you will get all kinds of cryptic errors when building! + +#. Under ``cosm/hal//subsystem/robot_available_actuators.hpp`` add an + entry for your agent to define the actuators that it has. If you don't define + the actuators here, you will get all kinds of cryptic errors when building! + +#. Try to build, fixing the inevitable compiler errors. If no errors--hooray for + you! If you are less lucky, fix the errors, keeping in mind the following: + + - Many seemingly intractable problems of the nature of "these things just + don't fit together" can be solved via a layer of indirection somewhere. + + If there are files which just won't compile, consider modifying the contents + of the COSM components to not build them. This is LAST RESORT: COSM has been + built with enough different agent and platform types that things are + generally organized well enough that it should be possible to accommodate any + additional agent type. + +#. If you have changed any of the XML parsers, update the :ref:`controller + ` and/or :ref:`swarm manager + ` documentation. + +#. Update the master table of the stuff that HAL/PAL support in the README. diff --git a/docs/src/modules.rst b/docs/src/modules.rst new file mode 100644 index 00000000..ea73a457 --- /dev/null +++ b/docs/src/modules.rst @@ -0,0 +1,44 @@ +.. Copyright 2022 John Harwell, All rights reserved. + +.. _ln-cosm-modules: + +===================== +COSM Software Modules +===================== + +High level summaries of COSM's main modules providing reusable (but not +necessarily generic functionality in MAS projects) are below; for full details +see the API. + + +- Artificial potential fields for navigation and flocking: :cosm:`cosm::apf2D`. + +- Platform Abstraction Layer (PAL): :cosm:`cosm::pal`. + +- Hardware Abstraction Layer (HAL): :cosm:`cosm::hal`. + +- Task allocation. Various methods from the swarm robotics literature, most of + which do not require communication. + +- Flocking. Also metrics and collectors. :cosm:`cosm::flocking` and + :cosm:`cosm::spatial::strategy::flocking`. + +- Common agent subsystems: :cosm:`cosm::subsystem` + + - Sensing and Actuation (SAA) + + - Perception + +- Foraging: block distribution, block motion, injection of perfect information + about blocks and caches. Metrics and collectors. :cosm:`cosm::foraging`. + +- General kinematics definitions for interfacing with ROS and other platforms: + :cosm:`cosm::kin`. + +- Convergence measurements of different types; metrics and + collectors. :cosm:`cosm::convergence`. + +- Injection of environmental and population dynamics; metrics and + collectors. :cosm:`cosm::tv`. + +- Simple management of arena state via grid: :cosm:`cosm::arena`. diff --git a/docs/src/setup/index.rst b/docs/src/setup/index.rst new file mode 100644 index 00000000..ef5d9bd8 --- /dev/null +++ b/docs/src/setup/index.rst @@ -0,0 +1,121 @@ +.. Copyright 2022 John Harwell, All rights reserved. + +.. _ln-cosm-setup: + +=============== +Setting Up COSM +=============== + +User Setup +========== + +#. Install/Setup Dependencies + + - :ref:`RCPPSW user setup ` + +#. Install COSM package(s). + +Developer Setup +=============== + +#. COSM uses `LIBRA `_ so go to + :ref:`ln-libra-req` and install any needed packages. + +#. Setup COSM's dependencies (packages is fine, unless you'll be modifying the + dependencies too): + + - :ref:`RCPPSW user setup ` + + +#. Clone COSM and init LIBRA:: + + git clone git@github.com:jharwell/cosm.git + cd cosm + git submodule update --init --remote --recursive + +#. Build COSM. From the root of the repo:: + + mkdir build && cd build + cmake .. + + ```` is a list of cmake arguments. + + .. IMPORTANT:: COSM and LIBRA output **VERY** thorough summaries of their + build configuration, so check them to make sure you are + building what you think you are. + + + You can pass any option as part of ```` that LIBRA supports (see + :ref:`ln-libra-capabilities`). In addition, you must specify what + platform+agent type you will built COSM for via ``COSM_BUILD_FOR``. Options + are as follows (see :ref:`ln-cosm-support` for details): + + .. list-table:: + :header-rows: 1 + :widths: 10 10 + + * - Platform+Hardware/Agent Model + + - ``COSM_BUILD_FOR`` value + + * - ARGOS Foot-bot + + - ARGOS_FOOTBOT + + * - ARGoS Drone + + - ARGOS_DRONE + + * - ARGoS E-puck + + - ARGOS_EEPUCK3D + + * - ARGoS Pi-puck + + - ARGO_PIPUCK + + * - Extended TURTLEBOT3 with ROS + + - ROS_ETURTLEBOT3 + + Some example build commands and their meaning: + + .. list-table:: + :header-rows: 1 + :widths: 10 90 + + * - Command + + - Meaning + + * - + + :: + + cmake \ + -DCOSM_BUILD_FOR=ARGOS_FOOTBOT + + - Build for the ARGoS foot-bot, development build with default event + reporting/logging (inherited from RCPPSW). + + * - + + :: + + cmake \ + -DCOSM_BUILD_FOR=ARGOS_FOOTBOT \ + -DCMAKE_BUILD_TYPE=OPT \ + -DLIBRA_ER=NONE + + - Build for the ARGoS foot-bot, optimized build with no event reporting. + + * - + + :: + + cmake \ + -DCOSM_BUILD_FOR=ARGOS_DRONE \ + -DCMAKE_INSTALL_PREFIX=$HOME/.local + + - Build for the ARGoS drone, development build with default event + reporting, installing to a different location. diff --git a/docs/src/support.rst b/docs/src/support.rst new file mode 100644 index 00000000..7a416940 --- /dev/null +++ b/docs/src/support.rst @@ -0,0 +1,79 @@ +.. Copyright 2022 John Harwell, All rights reserved. + +.. _ln-cosm-support: + +================================ +Supported Platforms and Hardware +================================ + +.. _ln-cosm-support-pal: + +Platform Abstraction Layer (PAL) +================================ + +COSM provides a common API for several *platforms* (a platform is an arbitrary +simulator, middleware layer, etc.) which client applications/libraries can build +against, leading to MUCH cleaner, more modular code; all the complexity is +handled in the PAL bindings for the platform. Currently supported platforms are: + +- ARGoS (``_). + +- ROS (``_). For real robots *or* simulators which support ROS, + such as Gazebo or WeBots. + +.. _ln-cosm-support-hal: + +Hardware Abstraction Layer (HAL) +================================ + +COSM provides a common API for several different agent/robot models within each +supported platform which client applications or libraries can build against to +increase code reuse and reduce the complexity of building for different +agents/robots. Currently supported hardware platforms are: + +.. list-table:: + :header-rows: 1 + :widths: 10 80 10 + + * - Parent Platform + + - Hardware/Agent Model + + - Support Maturity + + * - ARGoS + + - MarXbot (``_); called the + foot-bot in ARGoS. + + - Mature and nearly feature-complete. + + * - ARGoS + + - Drone + (``_), + a flying drone from `IRIDIA `_. + + - Beta. Some gaps in feature set such as setting target yaw in addition to + position. + + * - ARGoS + + - Extended e-puck, based on the e-puck2 + (``_). + + - Alpha. Does not build cleanly. + + * - ARGoS + + - Pi-puck (``_), an + e-puck with a Raspberry Pi mounted on it. + + - Alpha. Does not build cleanly. + + * - ROS + + - Extended Turtlebot3, based on the Turtlebot3 + (``_). + + - Beta. Many features available for other robots are missing. diff --git a/docs/config/controllers.rst b/docs/src/usage/controllers.rst similarity index 82% rename from docs/config/controllers.rst rename to docs/src/usage/controllers.rst index 44ba84b8..95c8f25d 100644 --- a/docs/config/controllers.rst +++ b/docs/src/usage/controllers.rst @@ -1,4 +1,6 @@ -.. SPDX-License-Identifier: LGPL-2.0-or-later +.. SPDX-License-Identifier: MIT + +.. _ln-cosm-usage-xml-controllers: ============================ Controller XML Configuration @@ -38,14 +40,17 @@ The following root XML tags are defined for all controller types: - Parameters for task allocation. - * - ``sensing_subsystemQ3D`` + * - ``sensing_subsystem`` - Parameters for robot sensing subsystem. - * - ``actuation_subsystem2D`` + * - ``actuation_subsystem`` - Parameters for robot actuation subsystem. + * - ``flocking`` + + - Parameters for swarms performing flocking. ``output`` ========== @@ -115,7 +120,7 @@ XML configuration: ... ... ... @@ -145,10 +150,12 @@ XML configuration: ... - - + + .. + + + .. + ... /> @@ -170,8 +177,7 @@ XML configuration: + duration="INT"/> ... @@ -206,9 +212,7 @@ XML configuration: .. code-block:: XML - + ... @@ -238,8 +242,9 @@ XML configuration: ... - + + .. + ... /> @@ -261,7 +266,7 @@ XML configuration: ... ... ... @@ -767,30 +772,30 @@ XML configuration: ``method`` tag that can be one of [ ``harwell2019`` ]. -``sensing_subsystemQ3D`` +``sensing_subsystem`` ======================== - Required by: All controllers. - Required child attributes if present: none. -- Required child tags if present: [ ``proximity_sensor``, ``ground_sensor`` ]. +- Required child tags if present: none. - Optional child attributes: none. -- Optional child tags: none. +- Optional child tags: [ ``proximity_sensor``, ``env_sensor`` ]. XML configuration: .. code-block:: XML - + ... - + ... - - + + -``sensing_subsystemQ3D/proximity_sensor`` +``sensing_subsystem/proximity_sensor`` ----------------------------------------- Parameters for proximity sensor configuration. @@ -803,14 +808,14 @@ Parameters for proximity sensor configuration. .. code-block:: XML - + ... ... - + - ``fov`` - The angle range to the left/right of center in which obstacles are not ignored (outside of this range they are ignored, assuming the robot will @@ -825,7 +830,7 @@ Parameters for proximity sensor configuration. ROS; for compatibility of ROS robot controller code with ARGoS robot controller code, which does this by default. -``sensing_subsystemQ3D/ground_sensor`` +``sensing_subsystem/ground_sensor`` -------------------------------------- Parameters for ground sensor configuration. @@ -840,7 +845,7 @@ XML configuration: .. code-block:: XML - + ... ... - + For each of [``nest``, ``block``, ``cache``], the following child attributes are required: @@ -862,8 +867,8 @@ required: - ``consensus`` - How many of the ground sensors must have readings within the specified range in order for a detection to be triggered. -``actuation_subsystem2D`` -========================= +``actuation_subsystem`` +======================= - Required by: All controllers. - Required child attributes if present: none. @@ -875,45 +880,48 @@ XML configuration: .. code-block:: XML - + ... ... - + -``actuation_subsystem2D/apf_manager`` -------------------------------------- +``actuation_subsystem/apf_manager`` +----------------------------------- Parameters for the virtual forces used to control robot movement, based on the original paper :xref:`Arkin1987` and the tutorial in :xref:`SteeringTutorial`. - Required by: All controllers. - Required child attributes if present: none. -- Required child tags: none. +- Required child tags: [ ``nav`` ]. - Optional child attributes: none. -- Optional child tags if present: [ ``nav`` ]. +- Optional child tags if present: [ ``flocking`` ]. XML configuration: .. code-block:: XML - + ... + + ... + ... - + -``actuation_subsystem2D/apf_manager/nav`` -""""""""""""""""""""""""""""""""""""""""" +``actuation_subsystem/apf_manager/nav`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Parameters for the virtual forces used to control robot movement, based on the original paper :xref:`Arkin1987` and the tutorial in :xref:`SteeringTutorial`. @@ -929,10 +937,9 @@ XML configuration: .. code-block:: XML - + ... - -