-
Notifications
You must be signed in to change notification settings - Fork 49
Development Setup
The README provides most of the details for how to get started with the project, but it doesn't really talk about how to set up a full development environment on Linux (or Windows) for handling all of the CI checks that any Pull Requests will be subject to. This page provides all of the details you will need.
Everything should be done from a working directory.
mkdir $HOME/working
cd $HOME/working
When everything here is done, you should have the following directory structure:
working_blah/
├── bsl
├── build
├── doxygen
├── doxygen-build
├── hypervisor
├── llvm-project
├── llvm-project-build
└── microv
To get started, we will first compile the external projects that we depend on for CI.
Bareflank maintains it's own custom version of LLVM for two reasons. First, we have mods to Clang Tidy to ensure compliance with AUTOSAR. We have also added a number of additional rules that enforce some of the project's additional code style preferences. We also have our own branch of LLVM to ensure that everyone is using the same version of the compiler and most importantly, Clang Format. Each version of Clang Format fixes bugs that will have small modifications to the code with the same configuration file, so using the same version of Clang Format ensures the CI doesn't run into issues.
To start, run the following:
cd $HOME/working
git clone https://github.com/bareflank/llvm-project
cd $HOME/working/llvm-project
git checkout -b bsl-tidy
cd $HOME/working
mkdir $HOME/working/llvm-project-build
cd $HOME/working/llvm-project-build
To compile LLVM, use the following (make sure you choose your core count properly as LLVM will absolutely crash your system with 100% memory usage if you are not careful, on a 64, 128 thread CPU and make -j, LLVM consumes almost 200GB of RAM, so again, limit your core count based on RAM usage):
cmake ../llvm-project/llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;lld;compiler-rt" -DLLVM_INCLUDE_TESTS=OFF -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_DOCS=OFF -DCMAKE_CXX_COMPILER="clang++" -DCMAKE_C_COMPILER="clang"
make -j<number of cores>
Once this is done, add LLVM to your path so that you can use it
export PATH="$HOME/working/llvm-project-build/bin:$PATH"
We use a custom version of Doxygen for two reasons. The version of Doxygen in Ubuntu 20.04 is really old and does not support C++20 (it barely supports C++11). We however cannot just use the master branch as there are bugs there two (regressions really), so we have carefully picked a version of Doxygen that seems to work well based on guidance from Doxygen's maintainers. The other reason we use our own version of Doxygen is the same as LLVM, to stay on the same version so that we don't run into issues with CI.
To start, run the following:
cd $HOME/working
git clone https://github.com/bareflank/doxygen
mkdir $HOME/working/doxygen-build
cd $HOME/working/doxygen-build
To compile Doxygen, use the following:
cmake ../doxygen
make -j<number of cores>
Once this is done, add Doxygen to your path so that you can use it
export PATH="$HOME/working/doxygen-build/bin:$PATH"
To prevent ourselves from having to download the BSL and the Hypervisor (i.e., the Microkernel) constantly, we will clone these repos now and then tell the build system where to find everything.
To start, run the following:
cd $HOME/working
git clone https://github.com/bareflank/bsl
git clone https://github.com/bareflank/microv
git clone https://github.com/bareflank/hypervisor
mkdir $HOME/working/build
The following aliases allow you to quickly set up the build folder with a specific configuration. These work with Windows as well if you are using Git Bash. Add the following to your .bashrc:
alias b='cd $HOME/working/build'
alias h='cd $HOME/working/hypervisor'
alias m='cd $HOME/working/microv'
alias y='cd $HOME/working/bsl'
alias MICROV_RELEASE='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=RELEASE -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_MINSIZEREL='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=MINSIZEREL -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_DEBUG='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=DEBUG -DBSL_DEBUG_LEVEL=bsl::V -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_CLANG_TIDY='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=CLANG_TIDY -DBSL_DEBUG_LEVEL=bsl::VVV -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_CODECOV='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=CODECOV -DBSL_DEBUG_LEVEL=bsl::VVV -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_ASAN='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=ASAN -DBSL_DEBUG_LEVEL=bsl::VVV -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_UBSAN='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=UBSAN -DBSL_DEBUG_LEVEL=bsl::VVV -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_DEBUG_VV='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=DEBUG -DBSL_DEBUG_LEVEL=bsl::VV -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_DEBUG_VVV='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=DEBUG -DBSL_DEBUG_LEVEL=bsl::VVV -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
alias MICROV_DEBUG_NO_COLOR='b && rm -Rf * && cmake -DCMAKE_BUILD_TYPE=DEBUG -DBSL_DEBUG_LEVEL=bsl::V -DENABLE_CLANG_FORMAT=ON -DENABLE_DOXYGEN=ON -DBUILD_TESTS=ON -DHYPERVISOR_BUILD_EFI=ON -DENABLE_COLOR=OFF -DFETCHCONTENT_SOURCE_DIR_BSL=$HOME/working/bsl -DFETCHCONTENT_SOURCE_DIR_HYPERVISOR=$HOME/working/hypervisor $HOME/working/microv'
This should be your default. It slows down compilation times a little bit, but you do not want to correct Clang Tidy issues after you have written a ton of code as it is no exaggeration to say that you could end up with 1000 or more errors:
b
MICROV_CLANG_TIDY
make -j<number of cores>
With a Clang Tidy build, you can use the following commands to handle certain CI issues:
make format
make doxygen
make unittest
If your code has compilation errors, Clang Tidy can sometimes get weird depending on the type of compilation error. What will happen is Clang Tidy will complain that code does not adhere to a specific rule when it clearly does (and usually, it will dump a lot of these all at once). When this happens, use a Debug build and recompile. That will show the compilation errors. Once corrected, go back to a Clang Tidy build.
To start, run the following:
b
MICROV_DEBUG
make -j<number of cores>
With a debug build, you can use the following commands to handle certain CI issues:
make format
make doxygen
make unittest
To start, run the following:
b
MICROV_RELEASE
make -j<number of cores>
or
b
MICROV_MINSIZEREL
make -j<number of cores>
To deal with code coverage, you should set up your development environment for local coverage reports using LCOV. To do that, install the following:
sudo apt-get install lcov
wget https://github.com/mozilla/grcov/releases/download/v0.8.0/grcov-linux-x86_64.tar.bz2
tar xvf grcov-linux-x86_64.tar.bz2
sudo mv grcov /usr/bin/
sudo rm /usr/bin/gcov
sudo ln -s /usr/bin/llvm-cov-10 /usr/bin/gcov
This installs lcov and grcov and it tells your system to use llvm-cov instead of gcov by default which is needed because you cannot use gcov when you are compiling with LLVM. Once this is done, you can use the following:
b
MICROV_CODECOV
make -j<number of cores>
To generate a report, use the following:
make codecov-genhtml
This will put a coverage report into $HOME/working/microv/genhtml. Simply open the index.html using your favorite browser and you can see your coverage report.
The easiest way to do development is to have a host machine (can be whatever OS you want) and a test machine which has the OS you are targeting. To do development, SSH into the test machine and code, build and test from there. VSCode helps a lot here as it has a Remote Development extension that allows you to work on a test machine from your host machine, so everything is being done on the test machine, but the editor is running on the host machine. https://code.visualstudio.com/docs/remote/ssh
When using this set up, it helps to have SSH set up so that you do not have to login each time you have to reboot your test machine. https://code.visualstudio.com/docs/remote/troubleshooting
Of course you can use whatever set up you want, but this might be a good starting point if you don't have any specific preferences.
To actually build and run the project, see the README on the top of the repo as nothing changes there.