8.2. ev-cli¶
This python project currently consists of the following packages
ev_cli
: EVerest module auto generation
8.2.1. Purpose¶
ev_cli
has mainly two purposes. One is to generate C++ header files for defined interfaces, the other one
is to create/update auto generated files for modules (C++ only).
The first one is done in the build process of everest-core
. For this
you don’t need to install ev-dev-tools
by yourself, it happens automatically during the build process.
For the second purpose you need to install ev-dev-tools
to use it during development.
8.2.2. Install¶
There are two possibilites to use/install ev-dev-tools
.
You can use the automatically installed version from python venv in build directory or
you can install the python package manually.
8.2.2.1. Use automatically installed ev-dev-tools from python venv¶
Build everest-core
as explained in the Quick Start Guide.
This will create a python venv in your build directory.
You can activate it with:
cd build/
source ./venv/bin/activate
8.2.2.2. Install ev-dev-tools manually¶
To install ev_cli
manually from github repository:
python3 -m pip install git+https://github.com/everest/everest-utils.git@main#subdirectory=ev-dev-tools
8.2.3. ev-cli command line interface¶
The ev_cli
package comes with a command line tool, named ev-cli
.
It has the following subcommands
module: auto generation and update of EVerest modules from its interface and manifest definitions
interface: auto generation of C++ header files for defined interfaces
helpers: utility commands
To see a list of all subcommands and options, simply call:
ev-cli –help
Both the module and interface command have the following options in common:
–everest-dir: root directory of EVerest core or any directory containing interface and module definitions (default:
.
)–framework-dir: root directory of the EVerest framework, containing the schema definitions (default:
../everest-framework
)–clang-format-file: if C++ output should be formatted, set this to the path of the .clang-format file
8.2.3.1. Generating C++ header files for defined interfaces¶
Assuming that the interface definitions in json format are located at
./interfaces/*.json
, simply:
ev-cli interfaces generate-headers
This will generate the c++ header files for all interfaces and output them
to ./generated/include/generated
. To generate only a single interface, call:
ev-cli interfaces generate-headers InterfaceName.json
For each interface an Implementation.hpp
and Interface.hpp
header file will be generated. The former represents the implementers
view, and the latter the users view of the interface, when used in a
module.
8.2.3.2. Creating and updating auto generated files for modules (C++ only)¶
Assuming the modules are located at ./modules
and the initial
skeleton for a module named Example with its manifest in
./modules/Example/manifest.json
should be created, call:
ev-cli module create Example
This will create the following files inside the ./modules/Example
subdirectory
CMakeLists.txt
: build instruction file for CMakeld-ev.hpp
/ld-ev.cpp
: glue code files for this module to get hooked up by the EVerest frameworkExample.hpp
/Example.cpp
: header and source file for the module
Furthermore, for each interface provided by the module a subdirectory with the name of the interface id will be created. If, for example, the manifest looks like:
{
"description": "Example module",
"provides": {
"main": {
"description": "SampleInterface implementation",
"interface": "SampleInterface",
...
}
}
...
}
a subdirectory named main
will be created, including two files
SampleInterfaceImpl.hpp
and SampleInterfaceImpl.cpp
. The header
file declares the implementation of SampleInterface, which derives
from the auto generated interface header files from the previous
subsection.
Now it is up to the user to implement logic in the module and interface implementation cpp source files.
If the modules’ manifest.json
or inferface definitions, used by the
module, change, you can update the generated files by using:
ev-cli module update Example
Note:
cpp
source files will never be changed or overwritten by the update subcommand. The create subcommand only resets / overrides the files when using the--force
optionhpp
header files and theCMakeLists.txt
file will get updated, if its interface dependencies definitions change and the update subcommand is used. You can force an update by using the--force
option. During an update, the sections marked like:// ev@75ac1216-19eb-4182-a85c-820f1fc2c091:v1 ..... // ev@75ac1216-19eb-4182-a85c-820f1fc2c091:v1
will be kept. If you want to completely reset / override these files, you need to recreate the using create subcommand with the
--force
option.Generated files will never be deleted. So make sure, you do this if you, for example, change the interface ids or remove interfaces from the module
These additional options might be useful for the create and update subcommands:
--force
: force creation or update--diff
: don’t touch anything, only show a diff of what would be changed--only
: this option takes a comma separated list of files, that should be touched only. This is especially helpful, if you want to recreate only a single interface implementationcpp
file, because you changed the corresponding interface a lot. To get a list of possible files, you can simply call:ev-cli module create Example --only which
this would output for the above mentioned example:
Available files for category "core" cmakelists ld-ev.hpp ld-ev.cpp module.hpp module.cpp Available files for category "interfaces" main.hpp main.cpp
So calling:
ev-cli module create Example --only main.cpp,cmakelists --force
would recreate the
CMakeLists.txt
and themain/SampleInterfaceImpl.cpp
files, whereas:ev-cli module update Example --only module.hpp
would update only the module header file
Example.hpp
.
8.2.3.3. Auto generating NodeJS modules¶
tbd