-
-
Notifications
You must be signed in to change notification settings - Fork 8
Generated CMake Project Walkthrough
This wiki page contains detailed information on what is being generated by the commsdsl2comms utility. Please open one of the generated example projects, such as cc.demo1.generated in a separate browser tab or clone the project to your PC and follow the description below.
The generated CMake project has multiple folders.
The protocol definition itself is headers only library which can be found in the include folder.
The common fields which can be referenced by multiple messages reside in the field folder / namespace.
All the message classes are defined in the message folder / namespace.
All the available transport frames are defined in the frame folder / namespace.
All the available compile time configuration options of the protocol reside in the options folder / namespace.
The configuration of the doxygen documentation resides in the doc folder.
The CommsChampion Tools are there to allow debugging and visual analysis of the defined protocol. The cc_plugin folder contains source files for the protocol definition plugin. The plugin as well as the tools themselves require Qt5 libraries and intend to be used on the development PC.
The test folder contains test application(s), which can be used as code reference and to test the generated protocol definition. Please refer to Testing Generated Protocol Code wiki page for more details on how to use them.
Please open the main CMakeLists.txt file. It should list all the available options and configuration variables, something like this:
option (OPT_BUILD_TEST "Build and install test applications." OFF)
option (OPT_BUILD_PLUGIN "Build and install CommsChampion plugin." OFF)
option (OPT_WARN_AS_ERR "Treat warning as error" ON)
option (OPT_USE_CCACHE "Use of ccache on UNIX system" ON)
# Other parameters:
# OPT_QT_DIR - Path to custom Qt5 install directory.
# OPT_CC_MAIN_INSTALL_DIR - Path to CommsChampion external install directory (if such already built).
# OPT_TEST_OPTIONS - Class name of the options for test applications, defaults to demo1::options::DefaultOptions.
# OPT_TEST_INTERFACE - Class name of the interface for test applications, defaults to demo1::Message.
# OPT_TEST_FRAME - Class name of the frame for test applications, defaults to demo1::frame::Frame.
# OPT_TEST_INPUT_MESSAGES - All input messages bundle for test applications, defaults to demo1::input::AllMessages.
Option OPT_BUILD_TEST enables build of the Test Applications, while OPT_BUILD_PLUGIN enables build of the CommsChampion Tools Plugin. The OPT_WARN_AS_ERR option allows control of whether compilation warning causes an error and the OPT_USE_CCACHE controls usage of ccache utility on UNIX system to speed the repeating builds.
The OPT_QT_DIR variable allows finding and using Qt5 libraries required by the CommsChampion Tools and the plugin. It is especially useful on Windows systems.
As it was already mentioned the protocol definition uses COMMS library and the CommsChampion Tools Plugin requires CommsChampion Tools from the comms_champion project. The OPT_CC_MAIN_INSTALL_DIR allows having external build of the latter. If such is not provided, everything is built and installed internally.
The OPT_TEST_OPTIONS, OPT_TEST_INTERFACE, OPT_TEST_FRAME, and OPT_TEST_INPUT_MESSAGES variables allow customization and configuration of the test application(s), please refer to the Testing Generated Protocol Code wiki page for more details.
The following commands will install both COMMS library and the protocol definition headers in the install subdirectory.
Linux Environment
$> cd /generated/project/dir
$> mkdir build && cd build
$> cmake -DCMAKE_INSTALL_PREFIX=${PWD}/install ..
$> make install
Windows Environment
$> cd C:\generated\project\dir
$> mkdir build && cd build
$> cmake -G "NMake Makefiles" -DCMAKE_INSTALL_PREFIX=%cd%/install ..
$> nmake install
The installation command above just copies headers of the COMMS library as well as protocol definition into the installation location, there is no actual build process. Hence, the usage of CMAKE_BUILD_TYPE variable to specify type of the build does not make any difference.
In case the OPT_CC_MAIN_INSTALL_DIR variable is used to provide external installation directory of the COMMS library, the latter is NOT installed alongside the protocol definition library.
In addition to protocols headers installation, the CMake project also contains target doc_<proj_name> to build doxygen documentation of the protocol. For example for cc.demo1.generated it is:
Linux Environment
$> make doc_demo1
Windows Environment
$> nmake doc_demo1
In case the plugin build is enabled using OPT_BUILD_PLUGIN option, the CommsChampion Tools are built and installed as well. It is recommended to build Release version.
Linux Environment
$> cd /generated/project/dir
$> mkdir build.tools && cd build.tools
$> cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=${PWD}/install \
-DOPT_BUILD_PLUGIN=ON ..
$> make install
Windows Environment
$> cd C:\generated\project\dir
$> mkdir build.tools && cd build.tools
$> cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=%cd%/install -DOPT_BUILD_PLUGIN=ON \
-DOPT_QT_DIR=C:\Qt\5.6.3\msvc2015 ..
$> nmake install
NOTE usage of OPT_QT_DIR variable to specify path to Qt5 libraries on Windows system.
In case the CommsChampion Tools are build externally and path to its installation is provided using OPT_CC_MAIN_INSTALL_DIR variable, only the plugin without tools themselves is being built and installed.
In Windows environment the CMake project also defines deploy_qt5 target to deploy all the used Qt5 libraries to the installation directory. It invokes windeployqt.exe utility from used Qt5 installation.
$> nmake deploy_qt5
The build of test applications is enabled using OPT_BUILD_TEST. It is recommended to use non-release build configuration to have all the assert() checks being active.
Linux Environment
$> cd /generated/project/dir
$> mkdir build.test && cd build.test
$> cmake -DCMAKE_INSTALL_PREFIX=${PWD}/install -DOPT_BUILD_TEST=ON ..
$> make install
Windows Environment
$> cd C:\generated\project\dir
$> mkdir build.test && cd build.test
$> cmake -G "NMake Makefiles" \
-DCMAKE_INSTALL_PREFIX=%cd%/install -DOPT_BUILD_TEST=ON ..
$> nmake install
For more details on testing the protocol definition please refer to Testing Generated Protocol Code wiki page.