 |
AUI Framework
develop
Cross-platform base for C++ UI apps
|
|
AUI Framework
develop
Cross-platform base for C++ UI apps
|
AUI Boot is yet another package manager based on CMake. If a library uses CMake with good CMakeLists, AUI Boot in 99% cases can provide it for you into your project without additional tweaking. It downloads the library, compiles it and places it in ~/.aui folder for future reuse.
See AUI's repository to check out the import script with the latest version.
AUI Boot is a source-first package manager, however, it can pull precompiled packages instead of building them locally. At the moment, GitHub Releases page with carefully formatted archive names is the only supported option. AUI follows these rules, so AUI Boot can pull precompiled package of AUI.
To use a precompiled binary, you must specify a tag of a released version from releases page (for example, v6.2.1 or v7.0.0-rc.2). These packages are self-sufficient, i.e., all AUI's dependencies are packed into them, so it is the only downloadable thing you need to set up a development and building with AUI.
If you would like to force AUI Boot to use precompiled binaries only, you can set AUIB_FORCE_PRECOMPILED:
This way AUI Boot will raise an error if it can't resolve dependency without compiling it.
If usage of precompiled binaries break your build for whatever reason, you can set AUIB_NO_PRECOMPILED:
This way AUI Boot will never try to use precompiled binaries and will try to build then locally.
No matter using precompiled binaries or building them locally, it's convenient to cache AUI Boot cache (~/.aui) in your CIs:
This snippet is based on GitHub's cache action example.
GitHub used npm's package-lock.json in their example's primary key (key). We've adapted their example to AUI Boot and use CMakeLists.txt, as dependencies' versions are "locked" there.
Using a stricter primary key key with a bunch of additional keys restore-keys is essential. If a cache hit occurs on the primary key, the cache will not be uploaded back to GitHub cache so your primary key must differ when you update dependencies.
Don't worry updating dependencies: GitHub cache action will restore the cache by using one of fallback keys restore-keys in such case, so you would not lose build speed up. Additionally, since the cache hit occurred on non-primary key, the newer cache will be uploaded to GitHub so the subsequent builds will reuse it.
AUI Framework has a lot of modules and functionality, however, it never pretends to be all-in-one solution for everything. We value quality over quantity. It is just a basis (framework), where you are free to put whatever building blocks you want, and we encourage you to do so, particularly, by using 3rdparty libraries. Just don't forget to obey other projects' licensing conditions, which are, in common, pretty much applicable even for proprietary software.
As was said in the beginning of this page, if a library has a good CMakeLists.txt (which mostly true for all popular C++ libraries), it can be imported with AUI.Boot:
The first argument to auib_import is the library name, which is then passed to CMake's find_package in order to import the library to your project. So, valid library name should be specified. You can obtain the library name from the following places:
README.If library name is incorrect, AUI.Boot prints the following message:
Take a look on the last line:
sentry is a valid library name that should have been passed to auib_import.
The second argument to auib_import is the URL to the library's repository. You can copy&paste it from address bar from your web browser.
The VERSION argument is tag name or hash name. You can copy&paste the latest release version name from GitHub Releases page of the library (1), or discover their tags (2,3,4):
The optional CMAKE_ARGS argument is arguments passed to library's CMake configure, another point of customization by AUI.Boot. These arguments are library specific; their documentation can be found on library's respective documentation pages. You won't need to use that unless you want an advanced tinkering of the library.
After library is imported to the project, its imported target should be linked to your executable/library. As with library's name, the name of the imported target probably can be found in library's README. Additionally, starting from CMake version 3.21, AUI.Boot prints a handy line on configure time when a library is imported:
Here, you can see the imported target(s) name in braces, that one should be used with aui_link/target_link_libraries. The complete library import boilerplate is:
CMakeLists.txt:
src/main.cpp:
For more libraries, please visit https://github.com/aui-framework/boot.
AUI Boot does not have any hard dependencies on AUI, so it can be used to manage dependencies on non-AUI projects.
, where 'LIB' is external project name. For example, to import AUI as a subdirectory:
This action disables usage of precompiled binary.
If needed, downloads and compiles project. Adds an IMPORTED target. Built on top of find_package.
*.dll, *.so and *.dylib (in case of shared libraries) alongside your executables during configure time. See Runtime Dependency Resolution for more info.Specifies the package name which will be passed to find_package. See Importing 3rdparty libraries.
URL to the git repository of the project you want to import.
Uses add_subdirectory instead of find_package as project importing mechanism as if AUIB_<PackageName>_AS was specified.
The provided URL is pointing to zip archive instead of a git repository.
For large dependencies, this might be faster than pulling whole repository.
Forces find_package to use the config mode only.
Commit hash, tag or branch name to checkout.
When unspecified, AUI.Boot uses the latest version from main branch of the library. Once discovered, AUI.Boot never updates the library version.
List of components to import which will be passed to find_package. Also, passed as semicolon-separated list to dependency's CMakeLists.txt via AUIB_COMPONENTS variable.
Run cmake in specified directory, in relation to the pulled repo's root directory.
Replace/put the specified file from your project to the pulled repo's root directory as CMakeLists.txt.
This way you can customize the behavior of dependency's cmake.
Instead of building the dependency from sources, try to import the precompiled binaries first.
Specifies url prefix where the precompiled binaries downloaded from.
Overrides BUILD_SHARED_LIBS of the dependency, specifying SHARED or STATIC linking.
List of the package dependencies. Every dependency's root variable (${DEPENDENCY}_ROOT) is checked for existence and validness, then it passed directly to auib_imported target (via ${DEPENDENCY}_ROOT).
It is useful when some package root is implicitly defined in your project somewhere and aui.boot does not know about it, thus does not forward.
For example, your application uses aui.core module, which actually uses ZLIB:
When you also want to use ZLIB.
Without AUI.Boot, you'd place (and compile) another copy of ZLIB whose version may differ from ZLIB that aui.core uses, causing you to stuck with dependency hell:
With AUI.Boot, you'd not even use AUI.Boot's functions! Just use find_package(ZLIB REQUIRED) and link it to your application with target_link_libraries(YourApplication PRIVATE ZLIB::ZLIB), because AUI.Boot forwards location of used dependencies to your project. Your application and AUI are using the same ZLIB:
Another case is OpenSSL between aui.crypt and aui.curl:
Because libcurl is not a part of AUI, it uses standard CMake's function to find OpenSSL (find_package).
AUI distributions published on our GitHub releases page are produced with help of AUI Boot.
CMake-driven projects produce package configuration with configure_file:
Inside of aui-config.cmake.in, there's a line:
AUIB_DEPS contains cmake commands to resolve dependencies of your project. This variable is populated by auib_import calls inside your project during configure time. AUIB_DEPS contains auib_import calls.
As was mentioned, AUI Boot requires specially formatted (precompiled) package names to use them. For this to work, you can call auib_precompiled_binary inside of your root CMakeLists.txt which configures cpack to produce tar.gz with properly formatted name.
At last, use cpack to produce a package.
In some cases, AUI Boot might not cover your particular needs, and you would like to build without it. It is still not a recommended way of using AUI, as it is not fully covered with tests, and you're basically trying to complicate your life by hardcoding paths in your CMake lists and thus making hardly reproducible projects. Consider asking questions about AUI Boot on our GitHub page, and we'd help to adapt AUI Boot to your use case.
AUIB_DISABLE (=NO) CMake configure flag can be used to replace auib_import calls to find_package. In this scenario you will need to resolve AUI's dependencies in some other way (i.e, by using Conan).
find_package#AUI distributions published on our GitHub releases page are self-sufficient. That is, they have AUI's dependencies bundled, so they can be used by find_package, without even requiring AUI Boot.
AUI Boot follows AUI Project philosophy, i.e, simplify developers' life and improve experience as far as possible. We were needed a CMake-only solution, so we skipped external generators (i.e., those that introduce additional building layer over CMake).
Despite CMake itself is complex (spoiler: every build system is) but thanks to the complexity CMake actually does the job good enough and its scripting system thankfully allows to download files from internet (and not only that).
Introducing additional building layer literally multiplies the building complexity by two. Moreover, Android targets already introduce such a layer (called Gradle). For example, if we were using Conan, Android building process would have 4 layers: Gradle, CMake, Conan, CMake (yes, 2 CMake layers).
AUI Boot (and CPM) require CMake only and don't involve extra runtime.
That being said, let's overview alternatives:
AUI is a C++ project, thus it should use CMake for AUI itself and AUI-based applications. Configure? cmake ... Build? cmake --build .. Test? ctest .. Package? cpack .. CMake offers enough functionality for various use cases. Let's avoid creating an uncomfortable situation by involving snakes in the process of developing C++ applications, we have our own great tools already.
Contents