{"id":13720638,"url":"https://github.com/eclipse/cloe","last_synced_at":"2025-04-25T10:16:27.703Z","repository":{"id":36966084,"uuid":"267343861","full_name":"eclipse/cloe","owner":"eclipse","description":"Cloe","archived":false,"fork":false,"pushed_at":"2024-10-30T08:17:54.000Z","size":12489,"stargazers_count":47,"open_issues_count":34,"forks_count":23,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-25T10:16:18.787Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cloe.readthedocs.io","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-05-27T14:37:28.000Z","updated_at":"2025-02-24T07:55:44.000Z","dependencies_parsed_at":"2023-10-23T09:45:24.082Z","dependency_job_id":"fece5143-019a-4b84-b9ba-cd5e0c1b3562","html_url":"https://github.com/eclipse/cloe","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse%2Fcloe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse%2Fcloe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse%2Fcloe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse%2Fcloe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse","download_url":"https://codeload.github.com/eclipse/cloe/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250796358,"owners_count":21488713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:01:06.192Z","updated_at":"2025-04-25T10:16:27.695Z","avatar_url":"https://github.com/eclipse.png","language":"C++","funding_links":[],"categories":["Simulation"],"sub_categories":["Version Control"],"readme":"Eclipse Cloe\n============\n\nCloe empowers developers of automated-driving software components by providing\na unified interface to closed-loop simulation. It achieves this by abstracting\nover environment and vehicle simulators and building upon these.\n\n![Screenshot of the Cloe UI](docs/screenshot.png)\n\nCloe isn't a single tool. It is a set of components written in different\nlanguages employing different tools that work together:\n\n - Cloe runtime \u0026 engine (C++)\n - Cloe command line interface (Python)\n - Cloe web user interface (Javascript/React)\n\nContributing to the CLI and the UI is pretty straightforward, as these are\ntools that live more-or-less 100% in their respective subdirectories. The\nruntime and engine are a different story though.\n\nCloe is meant to be extended through plugins that build on the Cloe runtime and\nare integrated at runtime by the Cloe engine. These are written in C++, which\ndoesn't have a defacto method of packaging. Finding a solution for integrating\nC++ packages is always going to be a trade-off between ease-of-use for\ndevelopers and users. In our experience, it is better to require more from\ndevelopers than from users, as demanding too much from users usually ends up\nbackfiring with increased support issues.\n\nGetting Started\n---------------\n\nFor in-depth documentation, see our [website](https://cloe.readthedocs.io).\n\nFor building, deploying, and running the runtime and engine we use [Conan][1],\na modern C++ package manager. We currently have not published any Conan\npackages that can be downloaded directly. Building them yourself is pretty\nstraightforward.\n\nCurrently, we only support Linux or [WSL][2].\n\n### Installing Dependencies\n\nWe provide automatic dependency installation for [Ubuntu][3] from 18.04 to 22.04\nvia the `Makefile.setup` Makefile. You should inspect it before\nrunning the targets, as these will modify your system.\nOther distributions may work, if the packages are available.\n\n    git clone https://github.com/eclipse/cloe.git\n    cd cloe\n    sudo make install-system-deps\n    make install-python-deps\n\nYou may need to setup your Conan profile before continuing on to the next\npoint. In a pinch, the following steps should suffice:\n\n 1. Install Conan with Python.\n    ```\n    pip3 install --user --upgrade \"conan\u003c2.0.0\"\n    ```\n 2. Define a Conan profile, which defines the machine configuration.\n    ```\n    conan profile new --detect default\n    conan profile update settings.compiler.libcxx=libstdc++11 default\n    conan profile update settings.build_type=RelWithDebInfo default\n    ```\n    If everything works out, your Conan profile should look *something like* this.\n    ```console\n    $ conan profile show default\n    Configuration for profile default:\n    [settings]\n      os               = Linux\n      os_build         = Linux\n      arch             = x86_64\n      arch_build       = x86_64\n      compiler         = gcc\n      compiler.version = 9\n      compiler.libcxx  = libstdc++11\n      build_type       = RelWithDebInfo\n    ```\n\nSee the Conan [documentation][6] for more information on how to do this.\n\n### Building the Cloe Packages\n\nTo build all packages, you should run the following:\n\n    make export-vendor export-all\n    make -C meta package\n\nThis will export all Conan recipes from this repository and create the cloe\npackage. Conan will download and build all necessary dependencies. Should\nany errors occur during the build, you may have to force Conan to build\nall packages instead of re-using packages it finds:\n```\n    make -C meta package CONAN_OPTIONS=\"--build\"\n```\nRun `make help` to get an overview of the available targets we expect you to\nuse. For more details on how this is done, have a look at the Makefiles in the\nrepository root.\n\nIf you experience timeout issues waiting for Conan Center, you can slightly\nincrease Conan's timeout configuration like so:\n\n    export CONAN_REQUEST_TIMEOUT=360\n\n### Running Cloe\n\nSince Cloe is made up of many packages, running the Cloe engine directly is\nsomewhat tricky. Conan provides the `virtualrunenv` generator, which creates\nshell scripts that you can source, similar to Python's virtualenv. Or, you can\nuse the `cloe-launch` tool, in the `cli` directory, which wraps all this\nfunctionality for you in one convenient place.\n\nYou can install `cloe-launch` with `pipx` (or `pip`), but we recommend you just\nuse the make target:\n\n    make deploy-cli\n\nIf you want to install it in editable mode, you can use:\n\n    make -C cli editable\n\nThis has the advantage that any updates to the repository will be transparently\nused.\n\nOnce the `cloe-launch` tool is available, you can do one of the following:\n\n 1. Launch a shell with the environment adjusted:\n    \u003c!-- TODO: Update this example!! --\u003e\n    ```console\n    $ cloe-launch -v shell tests/conanfile_default.py\n    Source profile: tests/conanfile_default.py\n    Profile name: 7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c\n    Configuration:\n        ...\n    Runtime directory: /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c\n    Exec: conan install --install-folder /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c -g virtualenv -g virtualrunenv tests/conanfile_default.py\n    Exec: /bin/bash -c source /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c/activate_run.sh \u0026\u003e/dev/null \u0026\u0026 env\n    Exec: /bin/bash -c source /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c/activate_all.sh \u0026\u003e/dev/null \u0026\u0026 env\n\n    [cloe-shell] $ cloe-engine usage\n    Cloe 0.19.0 (2022-11-21)\n    ...\n    ```\n 2. Launch `cloe-engine` directly:\n    \u003c!-- TODO: Update this example!! --\u003e\n    ```console\n    $ cloe-launch -v exec conanfile.py -- usage\n    Source profile: tests/conanfile_default.py\n    Profile name: 7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c\n    Configuration:\n        ...\n    Runtime directory: /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c\n    Exec: conan install --install-folder /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c -g virtualenv -g virtualrunenv tests/conanfile_default.py\n    Exec: /bin/bash -c source /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c/activate_run.sh \u0026\u003e/dev/null \u0026\u0026 env\n    Exec: /bin/bash -c source /home/captain/.cache/cloe/launcher/7745ffb0e036192c8e29a8b8cc2b9571e7a72c8c/activate_all.sh \u0026\u003e/dev/null \u0026\u0026 env\n    Exec: /home/captain/.conan/data/cloe-engine/0.19.0/cloe/develop/package/218a01b0a23497c52f95fbb0967b2d6b1d9ac1e4/bin/cloe-engine usage\n    ---\n    Cloe 0.19.0 (2022-11-21)\n    ...\n    ```\n\nNote that the above examples show the verbose output of the `cloe-launch` tool.\n\n### Running Tests\n\nIntegration and system tests can be run to ensure that all the packages built\nare working together as expected:\n\n    make export-all smoketest-deps\n    make smoketest\n\nThis will build packages in the required configurations as defined by the\nprofiles in the `tests` directories in the various packages. Then it will\nrun all available BATS tests with each of the profiles.\n\nUnit tests are compiled and run during the build step of each package, so\nthis shouldn't need to be performed manually.\n\nSee the documentation on testing Cloe for more details.\n\n### Disabling Unit Tests\n\nYou can disable running unit tests by setting `CONAN_RUN_TESTS=0`,\nas documented in the [Conan Manual](https://docs.conan.io/1/reference/env_vars.html#conan-run-tests).\n\nAlternatively, you can also prevent the unit tests from being built\nin the first place, by setting `tools.build:skip_test=1` in the\nConan configuration, as documented\n[here](https://docs.conan.io/1/reference/config_files/global_conf.html?highlight=skip_test)\nand [here](https://docs.conan.io/1/reference/conanfile/tools/cmake/cmaketoolchain.html?highlight=skip_test).\n\nWhen using `make` to build the project, add this to the command line:\n\n    CONAN_OPTIONS=\"-c tools.build:skip_test=1\"\n\n## Building with Bazel\n\nBazel tooling is currently experimental, and is meant to support users\nwho already are using Bazel in their projects and are not afraid of\nproviding their own registries and modules for Cloe's dependencies.\n\n(That allows us to not have to vendor massive amounts of Bazel modules\nin this repository, of which Boost is the main problematic point.\nOnce Boost makes it into the Bazel Central Registry, it may be worthwhile\nto vendor the remaining libraries in this repository.)\n\nYou will need to create a `.bazelrc.user` file in the repository root\nwith the following contents:\n\n    common --registry=file:///path/to/your/bazel/registry\n\nThis file is ignored by Git to prevent you from exposing your secrets.\nThe registry should contain the following modules:\n\n    boost\n    cli11\n    esmini\n    incbin\n    inja\n    luajit (optional)\n    oatpp\n    open-simulation-interface\n    sol\n\nThe rest of the dependencies are taken from the Bazel Central Registry.\nSee `MODULE.bazel` for the full list.\n\n### Building Docker Images\n\nThe `Dockerfile` provided in the repository root can be used to create one\nor more Docker images. These can be used as devcontainers or simply to\ncreate Conan packages in a reproducible environment.\n\nThe `Makefile.docker` contains multiple targets to build, test, and\nrelease Docker images for the current Cloe version in the repository.\nRun `make -f Makefile.docker help` to get an impression of what is possible:\n\n    $ make -f Makefile.docker help\n    Usage: make target\n\n    Available Docker targets:\n      all                   build and test all Ubuntu versions\n      ubuntu-VERSION        build and test the Ubuntu VERSION image\n      build-all             build all Ubuntu versions\n      build-ubuntu-VERSION  build the Ubuntu VERSION image\n      test-all              build all Ubuntu versions\n      test-ubuntu-VERSION   test the Ubuntu VERSION image\n      run-ubuntu-VERSION    run the Ubuntu VERSION image\n      release-all           release all Ubuntu versions\n      release-ubuntu-VERSION release the Ubuntu VERSION image\n      remove-current-images remove and prune all cloe/cloe-engine:0.19.0 Docker images\n      remove-all-images     remove and prune all cloe/cloe-engine Docker images\n\n    User configuration:\n        CONAN_PROFILE=\n        PACKAGE_TARGET=\n        KEEP_SOURCES=\n        DOCKER_USER_ARGS=\n\n    Docker configuration:\n        UBUNTU_NAME=ubuntu\n        UBUNTU_VERSIONS=\\\n          18.04\n          20.04\n          22.04\n        DOCKER=DOCKER_BUILDKIT=1 docker\n        DOCKER_CONTEXT=/home/captain/cloe\n        DOCKER_NETWORK=host\n        DOCKER_IMAGE=cloe/cloe-engine:0.19.0\n        DOCKER_BUILD_ARGS=\\\n          --build-arg PROJECT_VERSION=0.19.0\n        DOCKER_RUN_ARGS=\\\n          -it\n          --rm\n\nBecause Docker images may be built in environments that have a proxy running,\nthe Makefile will automatically add the proxy variables if they are are\ndetected in the host environment.\n\nThe section `User configuration` shows variables that can be set to modify\nthe resulting Docker image; if they are empty here, then the defaults in\nthe `Dockerfile` are used, which should suffice for most use-cases.\n\nIf you want to use a different Conan remote from the default, you need to\ncopy `setup.sh.example` to `setup.sh` and modify the values to match your\nenvironment.\n\nNote that this build requires the use of docker buildx, which has been\navailable for some time. This allows us to mount secrets in at build time\nand also speeds up the build by the strategic use of caches.\n\nKnown Issues\n------------\n\n### Build-require 'protobuf' cannot be found in lockfile\n\nWhen using `build-all`, `cloe-osi` fails to build with:\n\n    ERROR: Build-require 'protobuf' cannot be found in lockfile\n\nSee the [upstream issue](https://github.com/conan-io/conan/issues/10544).\nIn Conan 1, a dependency in a lockfile is only in host or build context, not\nboth. Unfortunately, this is only fixed in Conan 2.\n\nThe use-case for build-all is to build everything in editable mode.\nFor that, use the new super-build instead of building individual packages.\n\n### Superbuild 'cloe' package \"provides the same functionality\" error\n\nWhen using the `cloe` super-build package in tests, you may run into the\nfollowing error:\n\n    ERROR: At least two recipes provides the same functionality:\n    - 'fable' provided by 'cloe/0.25.0@cloe/develop', 'fable/0.25.0@cloe/develop'\n    - 'cloe-runtime' provided by 'cloe/0.25.0@cloe/develop', 'cloe-runtime/0.25.0@cloe/develop'\n    - 'cloe-models' provided by 'cloe/0.25.0@cloe/develop', 'cloe-models/0.25.0@cloe/develop'\n\nThis problem occurs when both `cloe` and one of the packages that `cloe`\n*provides* are pulled in as dependencies. Ideally, Conan should then\nuse `cloe` instead, but it would appear that Conan, at least in v1,\nis unable to do this.\n\nThe `cloe` super-build package is primarily used for development purposes,\nand until these kinks can be worked out, you should use the set of\nindividual packages for production.\n\n\n[1]: https://conan.io\n[2]: https://docs.microsoft.com/en-us/windows/wsl/about\n[3]: https://ubuntu.com\n[5]: https://github.com/conan-io/conan-center-index/issues/950\n[6]: https://docs.conan.io/en/latest/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse%2Fcloe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse%2Fcloe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse%2Fcloe/lists"}