jaulib v1.3.0
Jau Support Library (C++, Java, ..)
|
This project's canonical repositories is hosted on Gothel Software.
This project provides general C++ collections, algorithms and utilities.
jaulib
was extracted from Direct-BT to enable general use and enforce better encapsulation, now it is utilized in multiple projects ranging from cryptography with Cipherpack, over-the-air (OTA) updates to computer graphics with Gamp.
It also provides a basic mechanisms to create a thin Java JNI binding as well as some Java JNI bindings for a subset of jaulib
.
Build and clang-tidy clean on C++20, passing all unit tests.
See C++ Minimum Requirements and Supported Platforms for details.
Up to date API documentation can be found:
See Direct-BT C++ API Doc.
C++20 is the minimum requirement for releases > 1.2.0.
Release 1.2.0 is the last version supporting C++17, see Changes.
Support for C++23 and C++26 will be added step by step.
SFINAE
and its utilization in type_traits
for C++ metaprogramming are greatC++ Named Requirements
are defined as concepts next to type traits
counterpartconstexpr
completeness in the STL
(e.g. std::string
)gcc
and clang
have matured enough for C++20 in 2024Language requirements
See supported platforms for details.
It is advised to include this library into your main project, e.g. as a git-submodule.
Then add jaulib/include/ to your C++ include-path and also add the C++ source files under jaulib/src/ into your build recipe.
The produced Java libraries are fully functional.
This library's build recipe are functional though, but currently only intended to support unit testing and to produce a Doxygen API doc.
lint
validationeclipse
and vscodium
integrationInstalling build dependencies on FreeBSD >= 13:
Install optional Java dependencies:
For Java ensure /etc/fstab
includes:
jau::fs::mount_image()
and jau::fs::umount()
are currenly not fully implemented under FreeBSD
, hence testing using cmake option -DTEST_WITH_SUDO=ON
is disabled.
To use URL streaming functionality via the curl
library in jau_io_util.hpp
and jau/io_util.cpp
, the cmake option -DUSE_LIBCURL=ON
must be set.
This also requires installation of the following packets:
Note: mini-httpd
is being used for unit testing URL streaming only.
Installing build dependencies on Debian >= 11 and Ubuntu >= 20.04:
If using the optional clang toolchain, perhaps change the clang version-suffix of above clang install line to the appropriate version.
After complete clang installation, you might want to setup the latest version as your default. For Debian you can use this clang alternatives setup script.
Install optional Java dependencies:
To test jau::fs::mount_image()
and jau::fs::umount()
under Linux
with enabled cmake option -DTEST_WITH_SUDO=ON
,
the following build dependencies are added
To use URL streaming functionality via the curl
library in jau_io_util.hpp
and jau/io_util.cpp
, the cmake option -DUSE_LIBCURL=ON
must be set.
This also requires installation of the following packets:
Note: mini-httpd
is being used for unit testing URL streaming only.
Following debug presets are defined in CMakePresets.json
debug
debug-gcc
debug
gcc
clang-tidy
debug-clang
debug
clang
clang-tidy
release
debug
release-gcc
gcc
clang-tidy
release-clang
clang
clang-tidy
Kick-off the workflow by e.g. using preset release-gcc
to configure, build, test, install and building documentation. You may skip install
and doc_jau
by dropping it from --target
.
Besides above CMakePresets.json
presets, JaulibSetup.cmake
contains hardcoded presets for undefined variables if
CMAKE_INSTALL_PREFIX
and CMAKE_CXX_CLANG_TIDY
cmake variables are unset, orJAU_CMAKE_ENFORCE_PRESETS
cmake- or environment-variable is set to TRUE
or ON
The hardcoded presets resemble debug-clang
presets.
Kick-off the workflow to configure, build, test, install and building documentation. You may skip install
and doc_jau
by dropping it from --target
.
The install target of the last command will create the include/ and lib/ directories with a copy of the headers and library objects respectively in your dist location.
Our cmake configure has a number of options, cmake-gui or ccmake can show you all the options. The interesting ones are detailed below:
JaulibPreset
cached variables for hardcoded presets are
CMAKE_BUILD_TYPE
BUILD_TESTING
CMAKE_C_COMPILER
CMAKE_CXX_COMPILER
CMAKE_CXX_CLANG_TIDY
CMAKE_CXX_STANDARD
JaulibSetup
cached variables for regular builds are
DEBUG
CMAKE_INSTALL_PREFIX
CMAKE_CXX_STANDARD
USE_LIBCURL
USE_LIBUNWIND
BUILDJAVA
Changing install path
Building debug build:
or
Enable/disable unit tests to build
Add unit tests requiring sudo
to build (default: disabled).
This option requires -DBUILD_TESTING=ON
to be effective.
Covered unit test requiring sudo
are currently
Linux
OSjau::fs::mount_image()
jau::fs::umount()
Using clang instead of gcc:
Building with clang and clang-tidy lint
validation
Disable stripping native lib even in non debug build:
Enable using libcurl
(default: disabled)
Enable using libunwind
(default: disabled)
Disable using C++ Runtime Type Information
(RTTI) (default: enabled)
Building debug and instrumentation (sanitizer) build:
Cross-compiling on a different system:
To build documentation run:
To build Java bindings:
Override default javac debug arguments source,lines
:
You may also invoke scripts/build.sh
, which resolves installed environment variables like JAVA_HOME
and JUNIT_CP
as well as building and distributing using os_arch
type folders.
scripts/setup-machine-arch.sh
.. generic setup for all scriptsscripts/build.sh
.. initial build incl. install and unit testingscripts/rebuild.sh
.. rebuildscripts/build-cross.sh
.. cross-buildscripts/rebuild-cross.sh
.. cross-buildscripts/test_java.sh
.. invoke a java unit testscripts/test_exe_template.sh
.. invoke the symlink'ed files to invoke native unit testsAlso provided is a cross-build script using chroot into a target system using QEMU User space emulation and Linux kernel binfmt_misc to run on other architectures than the host.
See Build Procedure for general overview.
You may use our pi-gen branch to produce a Raspi-arm64, Raspi-armhf or PC-amd64 target image.
Tested Eclipse 2024-03 (4.31).
IDE integration configuration files are provided for
https://download.eclipse.org/tools/cdt/releases/cdt-lsp-latest
C/C++ LSP Support
in the Eclipse CDT LSP Category
CMake Support
, install C/C++ CMake Build Support
with ID org.eclipse.cdt.cmake.feature.group
debug-clang
The Hardcoded CMake Presets will use build/default
as the default build folder with debug enabled.
Make sure to set the environment variable CMAKE_BUILD_PARALLEL_LEVEL
to a suitable high number, best to your CPU core count. This will enable parallel build with the IDE.
You can import the project to your workspace via File . Import...
and Existing Projects into Workspace
menu item.
For Eclipse one might need to adjust some setting in the .project
and .cproject
(CDT) via Eclipse settings UI, but it should just work out of the box.
Otherwise recreate the Eclipse project by
.project
and .cproject
File . New . C/C++ Project
and Empty or Existing CMake Project
while using this project folder.IDE integration configuration files are provided for
.settings/org.eclipse.jdt.core.prefs
describes the lint
behaviorFor VSCodium one might copy the example root-workspace file to the parent folder of this project (note the filename change) and adjust the path
to your filesystem.
Then you can open it via File . Open Workspace from File...
menu item.
clang-tidy
enabledclang-tidy
is too slow, just remove it from the settings file.clangd
will still contain a good portion of clang-tidy
checksSee Changes.