|
| 1 | +# Version 0.25.0 Release |
| 2 | + |
| 3 | +This release contains the initial implementation of Lua support with the new |
| 4 | +DataBroker and Signals concept. |
| 5 | + |
| 6 | +## Add Lua support |
| 7 | + |
| 8 | +Lua is a lightweight embedded language that can now be used to define simulation |
| 9 | +configuration and test execution and evaluation. |
| 10 | + |
| 11 | +For example: |
| 12 | + |
| 13 | +```lua |
| 14 | +cloe = require("cloe") |
| 15 | +proj = require("project") |
| 16 | +cloe.load_stackfile("existing_configuration.json") |
| 17 | +cloe.schedule_test { |
| 18 | + id = "e03fc31f-586b-4e57-80fa-ff2cba5ff9dd", |
| 19 | + on = events.start(), |
| 20 | + run = function(test, sync) |
| 21 | + cloe.log("info", "Entering test") |
| 22 | + test:wait_duration("1s") |
| 23 | + |
| 24 | + -- Enable Cruise Control |
| 25 | + proj.enable_hmi() |
| 26 | + test:wait_duration("4s") |
| 27 | + |
| 28 | + -- Set speed and increase |
| 29 | + local speed = cloe.signal(proj.Signals.VehicleSpeed).kmph() |
| 30 | + proj.buttons.plus.push("1500ms") |
| 31 | + test:wait_duration("4s") |
| 32 | + |
| 33 | + -- Check that new speed is higher than before but lower than |
| 34 | + -- the speed-limit. |
| 35 | + local new_speed = cloe.signal(proj.Signals.VehicleSpeed).kmph() |
| 36 | + test:assert_gt(new_speed, speed) |
| 37 | + test:assert_le(new_speed, proj.scenario.speed_limit) |
| 38 | + test:succeed() |
| 39 | + end |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +The above test-case is a hypothetical, yet realistic way that such a test can |
| 44 | +be written. The results are written to an output file and the terminal output |
| 45 | +in JSON format, so they can be easily processed. |
| 46 | + |
| 47 | +The engine comes with a new `shell` command, which allows you to launch an |
| 48 | +interactive Lua session or just run Lua files. |
| 49 | + |
| 50 | +A simulation with or without Lua can be run as before with the `run` command. |
| 51 | +The JSON stackfile interface is still supported and can be mixed with Lua. |
| 52 | +In particular, all the features in the stackfiles can be now used from Lua |
| 53 | +in a backwards-compatible way. Your existing test files do not need to be |
| 54 | +rewritten, but you can achieve better results by adding Lua or switching |
| 55 | +completely. |
| 56 | + |
| 57 | +See {doc}`the usage documentation <../usage/lua-introduction>` for more! |
| 58 | + |
| 59 | +## New probe sub-command |
| 60 | + |
| 61 | +The new `probe` sub-command of `cloe-engine` allows you to probe a simulation |
| 62 | +configuration with merged stack files. |
| 63 | + |
| 64 | +In this mode, a simulation is set up and all the participants are connected, |
| 65 | +probed, and then disconnected. That means: |
| 66 | + |
| 67 | +- the simulation must be fully configured, |
| 68 | +- failures may occur during connection phase, and |
| 69 | +- scripts included must be correct. |
| 70 | + |
| 71 | +The output of the probe is a JSON written to stdout: |
| 72 | + |
| 73 | +```json |
| 74 | +{ |
| 75 | + "http_endpoints": [ "/endpoints", ... ], |
| 76 | + "plugins": { |
| 77 | + "PLUGIN_NAME": "PLUGIN_PATH", |
| 78 | + ... |
| 79 | + }, |
| 80 | + "signals": { |
| 81 | + "SIGNAL_NAME": "DESCRIPTION", |
| 82 | + ... |
| 83 | + }, |
| 84 | + "tests": { |
| 85 | + } |
| 86 | + "trigger_actions": [ "ACTION1", "..." ], |
| 87 | + "trigger_events": [ "EVENT1", ... ], |
| 88 | + "uuid": "UUID", |
| 89 | + "vehicles": { |
| 90 | + "NAME": [ "COMPONENT1", ... ] |
| 91 | + } |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +The tests section is only defined if the simulation configuration |
| 96 | +contains Lua that defines tests (via `cloe.schedule_test()` API). |
| 97 | +You can use tools like `jq` to further filter and refine the output. |
| 98 | + |
| 99 | +Examples: |
| 100 | + |
| 101 | + cloe-engine probe tests/test_nop_smoketest.json |
| 102 | + cloe-engine probe my_lua_test.lua | jq -r '.tests | keys | .[]' |
| 103 | + |
| 104 | +## Engine changes |
| 105 | + |
| 106 | +- Add `--output-path` option to ``run`` command. |
| 107 | + |
| 108 | + This allows you to specify where output files should be written without having |
| 109 | + to configure it in the stackfile. |
| 110 | + |
| 111 | +- Remove `--distinct` flag from ``check`` command. |
| 112 | + |
| 113 | + It wasn't used much and complicated the code. This old behavior can be easily |
| 114 | + achieved with outside tooling, such as `xargs` and `find`, so there is no loss |
| 115 | + in functionality overall. |
| 116 | + |
| 117 | +## Tooling changes |
| 118 | + |
| 119 | +The `cloe` Conan package was previously a meta-package containing all packages |
| 120 | +created from this repository. |
| 121 | + |
| 122 | +This package is being discontinued from this version of Cloe. |
| 123 | +It was primarily meant for testing purposes, and thanks to new dependencies |
| 124 | +in our project and the limitations of Conan 1, it no longer fulfills this role. |
| 125 | + |
| 126 | +**Migration:** |
| 127 | +> If you have been using the `cloe` package as a first-level dependency, then |
| 128 | +> you will need to specify all the packages individually that you need. |
| 129 | +> |
| 130 | +> It is highly recommended to split your build Conanfile from your deployment |
| 131 | +> Conanfile. For your controller build Conanfile, you generally only need: |
| 132 | +> |
| 133 | +> def requirements(self): |
| 134 | +> def cloe_requires(dep): |
| 135 | +> self.requires(f"{dep}/0.25.0@cloe/develop") |
| 136 | +> |
| 137 | +> cloe_requires("cloe-runtime") |
| 138 | +> cloe_requires("cloe-models") |
| 139 | +> |
| 140 | +> And for your deployment Conanfile you should only include the plugins you |
| 141 | +> actually use: |
| 142 | +> |
| 143 | +> def requirements(self): |
| 144 | +> def cloe_requires(dep): |
| 145 | +> self.requires(f"{dep}/0.25.0@cloe/develop") |
| 146 | +> |
| 147 | +> cloe_requires("cloe-engine") |
| 148 | +> cloe_requires("cloe-plugin-clothoid-fit") |
| 149 | +> cloe_requires("cloe-plugin-frustum-culling") |
| 150 | +> cloe_requires("cloe-plugin-gndtruth-extractor") |
| 151 | +> cloe_requires("cloe-plugin-noisy-sensor") |
| 152 | +> cloe_requires("cloe-plugin-esmini") |
| 153 | +> self.requires("your-plugin") |
| 154 | +> self.requires("esmini-data/2.37.4@cloe/stable") |
| 155 | +> |
| 156 | +> # Override as needed: |
| 157 | +> self.requires("esmini/2.37.4@cloe/stable", override=True) |
| 158 | +> self.requires("fmt/9.1.0", override=True) |
| 159 | +> self.requires("inja/3.4.0", override=True) |
| 160 | +> self.requires("nlohmann_json/3.11.3", override=True) |
| 161 | +> self.requires("incbin/cci.20211107", override=True) |
| 162 | +> self.requires("boost/1.74.0", override=True) |
| 163 | +> self.requires("zlib/1.2.13", override=True) |
| 164 | +> self.requires("protobuf/3.21.12", override=True) |
| 165 | +
|
| 166 | +For developing Cloe, the root Conanfile is now a super-build of Cloe, which |
| 167 | +provides a vastly simplified workflow for editing Cloe code: |
| 168 | + |
| 169 | + echo "0.26.0-nightly" > VERSION |
| 170 | + make editable |
| 171 | + |
| 172 | +And then iterate changes and (re-)builds with |
| 173 | + |
| 174 | + make all |
| 175 | + |
| 176 | +This is a boon to development, as we make `cloe` editable and only have to work |
| 177 | +with a single package. It also massively speeds up compilation: |
| 178 | + |
| 179 | +- Conan and CMake configuration is only performed once. |
| 180 | +- All cores can now be utilized much more effectively during the build process. |
| 181 | + |
| 182 | +The main Makefile has been adjusted for this: |
| 183 | + |
| 184 | +- `status` is now `status-all` |
| 185 | +- `deploy` is now `deploy-all` |
| 186 | +- `clean` is now `clean-all` |
| 187 | +- `purge` is now `purge-all` |
| 188 | + |
| 189 | +The following top-level Make targets just refer to `cloe` super-build package: |
| 190 | + |
| 191 | +- `package` |
| 192 | +- `smoketest` |
| 193 | +- `smoketest-deps` |
| 194 | +- `status` |
| 195 | +- `export` |
| 196 | + |
| 197 | +Finally, we moved all tests into project root tests directory. |
| 198 | +We still support multiple profiles, but this makes it easier to support the |
| 199 | +cloe super-build and should also make it easier to develop and maintain tests. |
| 200 | + |
| 201 | +## Bazel Build |
| 202 | + |
| 203 | +We have added experimental support for Bazel builds. Bazel is a promising |
| 204 | +build system for enterprises, as it radically simplifies the build tooling |
| 205 | +required. We have a single tool Bazel, instead of three or four layers of tools; |
| 206 | +in our case: Make -> Conan -> CMake -> Make/Ninja. |
| 207 | + |
| 208 | +The `.bazelrc.user` file needs to be configured in order for certain third-party |
| 209 | +modules to be found (see repository `README.md`) |
| 210 | + |
| 211 | +- `bazel build //...` builds everything in the project. |
| 212 | +- `bazel test //...` runs all tests. |
| 213 | +- `bazel run :cloe_shell` launches a shell wherein `cloe-engine` is available. |
| 214 | + |
| 215 | +Full feature parity with Conan is not yet achieved. For example, there is |
| 216 | +no Bazel build for VTD or ESmini yet. Contributions are welcomed! :-) |
| 217 | + |
| 218 | +## Library changes |
| 219 | + |
| 220 | +At various places, `boost::optional` and `boost::filesystem` types and methods are |
| 221 | +replaced by their C++17 counterparts. This makes our libraries more lightweight |
| 222 | +by reducing their dependence on Boost. |
0 commit comments