Compilation and Installation

CMake is used to create the necessary build files (Unix Makefiles on Linux, MS Visual Studio Solutions on Windows, etc) for compiling the OpenJAUS SDK source code.

Important Notes:

1. We make a number of assumptions on how the average user will be building/using our code base, in order to make Getting Started as simple as possible. If you have more complex needs, you may need to modify the CMakeLists.txt files directly or set cmake variables to modify our default behavior.
2. The provided CMake files were tested using CMake v3.22. They should work with CMake v3.14 or later but this has not been verified.

Compiling the Code

Building the SDK will build the OpenJAUS libraries and the Examples.

Note

The 2024.x SDK releases contain both the latest versions of the SAE and RAS-G IOP service sets and the older versions available in the 2023.x SDK releases. Libraries for all service sets will build by default. There are CMake options available to specify if you only want to build libraries for the latest or older service sets.

Linux

1. Install CMake (See Note 2 above)
   • Ubuntu 22.04 ships with CMake 3.22.1
2. Open a command terminal window
3. Go to the org.openjaus.sae-sdk.cpp folder
   • cd {sdk_parent}/org.openjaus.sae-sdk.cpp
     • The path that contains the unzipped org.openjaus.sae-sdk.cpp folder will be referred to as {sdk_parent}
4. Create a build folder to house the CMake generated build files. This keeps the source and build files separated
   • mkdir build
5. Go into the newly created build folder
   • cd build

6. Run CMake from within the build folder and have it point to the directory that contains the CMakeLists.txt file

   • cmake ..
     • This will use the default CMake generator which is Unix Makefiles on Linux. If you want to use a different generator you will need to specify as such using CMake's -G option.
     • By default the headers and libraries will be installed to {sdk_parent}/install/{OS}-{Architecture} vs CMake's default location (/usr/local/).
       • This removes the need to have root access to do the install and keeps the openjaus files isolated for easier removal later.
       • If you want to use CMake's default location then set the OJ_USE_DEFAULT_INSTALL_DIR=OFF
         • cmake -DOJ_USE_DEFAULT_INSTALL_DIR=OFF ..
       • If you want to install to a custom location set OJ_OVERRIDE_DEFAULT_INSTALL_DIR=ON and use the CMAKE_INSTALL_PREFIX CMake variable when running the initial cmake command
         • cmake -DOJ_OVERRIDE_DEFAULT_INSTALL_DIR=ON -DCMAKE_INSTALL_PREFIX={my_install_location} ..

7. Run make to build the code

   • make all
     • If you have multi-core CPU you can have make split the build across multiple "jobs".
     • For example, to use 4 jobs for the compile:
       • make -j4 all
8. Install the header files and built binaries
   • make install
     • By default the compiled libraries and applications will be installed to {sdk_parent}/install/{OS}-{Architecture} vs cmake's default location (/usr/local). This removes the need to have root access to do the install.
   • See Installation Tips

Windows

1. Install CMake (See Note 2 above)
2. Open a command terminal window
3. Go to the org.openjaus.sdk.cpp folder
   • cd {sdk_parent}/org.openjaus.sdk.cpp
     • The path that contains the unzipped org.openjaus.sae-sdk.cpp folder will be referred to as {sdk_parent}
4. Create a build folder to house the CMake generated build files. This keeps the source and build files separated
   • mkdir build
5. Go into the newly created build folder
   • cd build

6. Run CMake from within the build folder and have it point to the directory that contains the CMakeLists.txt file

   • cmake ..
     • This will use the default CMake generator which is typically Visual Studio Project/Solution on Windows. If you want to use a different generator you will need to specify as such using CMake's -G option.
     • By default the headers and libraries will be installed to {sdk_parent}/install/{OS}-{Architecture} vs CMake's default location (c:/Program Files/${PROJECT_NAME}).
       • This removes the need to have Administrator access to do the install.
       • If you want to use CMake's default location then set the OJ_USE_DEFAULT_INSTALL_DIR=OFF
         • cmake -DOJ_USE_DEFAULT_INSTALL_DIR=OFF ..
       • If you want to install to a custom location set OJ_OVERRIDE_DEFAULT_INSTALL_DIR=ON and use the CMAKE_INSTALL_PREFIX CMake variable when running the initial cmake command
         • cmake -DOJ_OVERRIDE_DEFAULT_INSTALL_DIR=ON -DCMAKE_INSTALL_PREFIX={my_install_location} ..

7. Open generated solution in MS Visual Studio and build

   • By default the headers and libraries will be installed automatically after the build to the configured install location.
     • This removes the need to run the install manually.
     • If you the install location is configured to the cmake default then Visual Studio will need to have administrator access to do the install.
   • If you don't want the install to run automatically set CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD=OFF when running CMake
     • • cmake -DCMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD=OFF ..

ARM Linux (Cross-Compiling)

Note: The instructions are slightly different depending in the version of the linux that the code is intended to run against. Basically, the compiler version being used to cross-compile must match the version provided on the board.

Using a Linux Host

1. Install the ARM GNU Toolchain
   • For running on Ubuntu 18.04:
     • Download the Linary gcc7 toolchain
     • Unzip the archive
     • Add {install location}/bin to the path
       • Verify you can run aarch64-none-linux-gnu-g++ --version
2. Install CMake if necessary
3. Open a command terminal window
4. Go to the org.openjaus.sae-sdk.cpp folder
   • cd {sdk_parent}/org.openjaus.sae-sdk.cpp
     • The path that contains the unzipped org.openjaus.sae-sdk.cpp folder will be referred to as {sdk_parent}
5. Create a build folder to house the CMake generated build files. This keeps the source and build files separated
   • mkdir build
6. Go into the newly created build folder
   • cd build
7. Copy the cross-compile toolchain file to the build folder
   • cp ../org.openjaus.buildtools.cmake/toolchains/linaro_gcc7.cmake .

8. Run cmake using the toolchain file

   • cmake -D CMAKE_TOOLCHAIN_FILE=linaro_gcc7.cmake ..
     • This will use the default CMake generator which is Unix Makefiles on Linux. If you want to use a different generator you will need to specify as such using CMake's -G option.
     • By default the headers and libraries will be installed to {sdk_parent}/install/{OS}-{Architecture} vs CMake's default location (/usr/local/).
       • This removes the need to have root access to do the install and keeps the openjaus files isolated for easier removal later.
       • If you want to use CMake's default location then set the OJ_USE_DEFAULT_INSTALL_DIR=OFF
         • cmake -D OJ_USE_DEFAULT_INSTALL_DIR=OFF ..
       • If you want to install to a custom location set OJ_OVERRIDE_DEFAULT_INSTALL_DIR=ON and use the CMAKE_INSTALL_PREFIX CMake variable when running the initial cmake command
         • cmake -D OJ_OVERRIDE_DEFAULT_INSTALL_DIR=ON -D CMAKE_INSTALL_PREFIX={my_install_location} ..

9. Build

   • cmake --build .
10. Install
    • cmake --install .
      • By default the compiled compiled libraries and applications will be installed to {sdk_parent}/install/{OS}-{Architecture} vs cmake's default location (/usr/local). This removes the need to have root access to do the install.
    • See Installation Tips

Using a Windows Host

1. Install MinGW-w64
   • Go to winlibs.com
   • Download the appropriate UCRT runtime archive
     • GCC 12.2.0 + LLVM/Clang/LLD/LLDB 15.0.6 + MinGW-w64 10.0.0 (UCRT) - release 3
   • Unzip mingw64 folder
   • Add {ming64 location}/bin to the path
     • Verify you can run mingw32-make --version
2. Install the Arm GNU Toolchain
   • For running on Ubuntu 18.04:
     • Download the Linaro gcc7 toolchain
     • Unzip the archive (7-Zip)
     • Add {install location}/bin to the path
       • Verify you can run aarch64-none-linux-gnu-g++ --version
3. Open a command terminal window
4. Go to the org.openjaus.sae-sdk.cpp folder
   • cd {sdk_parent}/org.openjaus.sae-sdk.cpp
     • The path that contains the unzipped org.openjaus.sae-sdk.cpp folder will be referred to as {sdk_parent}
5. Create a build folder to house the CMake generated build files. This keeps the source and build files separated
   • mkdir build
6. Go into the newly created build folder
   • cd build
7. Copy the cross-compile toolchain file to the build folder
   • cp ../org.openjaus.buildtools.cmake/toolchains/linaro_gcc7.cmake .
     • cp is the command to copy files when using PowerShell. If you're using Windows Command Prompt, the command will be different
8. Run cmake using the toolchain file
   • cmake -G “MinGW Makefiles” -D CMAKE_TOOLCHAIN_FILE=linaro_gcc7.cmake ..
     • Cross-compiling requires the generation of MinGW Makefiles versus Microsoft Visual Studio files
9. Build
   • cmake --build .
10. Install
    • cmake --install .
      • By default the compiled application(s) will be installed to {openjaus_sdk_root}/install/{OS}-{Architecture} vs cmake's default location. This removes the need to have root access to do the install
    • See Installation Tips

Installation Tips

There are two times where the installation location of the OpenJAUS SDK libraries and/or headers are important:

1. When compiling a binary that depends on the OpenJAUS SDK libraries
2. When running a binary that depends on the OpenJAUS SDK libraries

During compile, the compiler must be able to find the OpenJAUS SDK headers to resolve the class declarations and the linker must be able to find the OpenJAUS SDK libraries to link against the class definitions. If a library is dynamic or shared (.so file in Linux of .dll in Windows), then at runtime the binary must be able to find the library to load it into memory for use.

Discovering the location of the OpenJAUS SDK libraries at compile time can be automatically handled by CMake using the find_package command. However, discovering the location of the OpenJAUS SDK libraries at runtime varies by operating system. The following sections describe how to handle this for the different operating systems.

Linux

When building for desktop Linux, by default the OpenJAUS SDK will be compiled into shared objects that are installed to {sdk_parent}/install/{OS}-{Architecture}. The installation path is intentionally different that the default cmake installation path to avoid the need for root access. However, this can cause issues when attempting to run a binary that is compiled against the OpenJAUS SDK libraries as the binary may not be able to find the OpenJAUS shared object because they are not in the default search path. There are a few ways to address this:

1. Install the OpenJAUS SDK libraries to a location in the default search path
   • cmake -DOJ_USE_DEFAULT_INSTALL_DIR=ON ..
     • This will install the OpenJAUS SDK libraries to /usr/local/lib and the headers to /usr/local/include
     • This will require root access to do the install
2. Add the OpenJAUS SDK library path to the LD_LIBRARY_PATH environment variable before running the binary
   • export LD_LIBRARY_PATH={sdk_parent}/install/{OS}-{Architecture}/lib:$LD_LIBRARY_PATH
     • This will only work for the current terminal session
     • If you want to make this permanent then add the above line to your ~/.bashrc file
3. [Preferred] Use ldconfig to specify the location of the OpenJAUS SDK libraries
   • See the ldconfig man page for more details

Option 3 is the preferred method as it doesn't require root access during installation, can be easily reverted, and is permanent.

** Alternative - Static Libraries **

You can also build the OpenJAUS SDK as static libraries which will remove this issue completely as the final binary will not depend on any external libraries. To do this you will need to set the BUILD_SHARED_LIBS CMake variable to OFF when running CMake:

• cmake -DBUILD_SHARED_LIBS=OFF ..

More information:

• CMake Help
• CMake Tutorial

Windows

When building for Windows, by default the OpenJAUS SDK will be compiled into shared libraries (dlls) that are installed to {sdk_parent}/install/{OS}-{Architecture}. The installation path is intentionally different than the default cmake installation path to avoid the need for root access. However, this can cause issues when attempting to run an application that is compiled against the OpenJAUS SDK libraries as the application may not be able to find the OpenJAUS dlls because they are not in the default search path. See Windows DLL Search Order for more details.

The preferred method to address this issues is to install the OpenJAUS SDK dlls to the same folder as the final binary as it doesn't require root access during installation, can be easily reverted, each application is stand-alone, and dll versioning is not an issue.

ARM Linux

When building for ARM Linux, by default the OpenJAUS SDK will be compiled into static libraries. As such, a binary that is compiled against the OpenJAUS SDK libraries will not depend on any external OpenJAUS libraries at runtime. If you would like to use shared objects instead and you will need to set the BUILD_SHARED_LIBS CMake variable to ON when running CMake:

• cmake -DBUILD_SHARED_LIBS=ON ..

You will then need to make the shared objects available during runtime using the same methods as described in the Desktop Linux section.

More information:

• CMake Help
• CMake Tutorial