"We homebrew developers are programmer cats 🐱. As such, we need some kind of recreational substance that alleviates the pain of using/invoking CMake, as well as managing multiple closely linked components. In other words, we need a Magic™ build tool that orchestrates everything."
-- from the Book of Lenny, 10:30
Catnip is a command-line tool designed to improve the workflow around CMake-based projects, especially when using devkitPro tools.
Catnip can be used to automate development tasks with pure CMake projects.
It also supports Catnip-laced projects containing one or more packages, each
defining one or more presets specifying how to configure and build the package.
Packages and presets in Catnip-laced projects are defined with a custom CMake-based API.
Pure CMake projects are considered to contain a single main package, with release (default) and debug presets.
Catnip needs to know the path to the top level folder of the project, which is known as the source root directory.
This can be specified in the command line (-S <path>), as an environment variable (CATNIP_ROOT), or
detected automatically. In the latter case, Catnip uses the current working directory, or the closest parent
directory containing a .catnip_root file.
Catnip creates and manages a build folder, where all generated files and compilation outputs will be stored.
By default (and also traditionally) this is <catnip-root>/build, although it can be explicitly set in
the command line (-B <path>) or with an environment variable (CATNIP_BUILD_DIR).
The build folder contains multiple subfolders named <package>.<preset>, one for each configured preset of each package.
The build folder also keeps a default CMake cache, populated using user-provided command line arguments, whose values
will be forwarded to CMake by default when configuring presets. This makes it possible to set custom flags once and
have them be used in subsequent runs, persisting even after cleaning build subfolders. In addition, Catnip is capable
of managing a dependency graph between packages/presets, which can be leveraged to ensure that certain required
components are built before others are allowed to be built.
Catnip is designed with support for cross compilation and devkitPro CMake as a first class feature. For this reason, it introduces the concept of
a Catnip toolset, which is inspired by the eponymous concept some CMake generators use (Visual Studio, Xcode).
In Catnip's case it is the bare name of a toolchain file (case-insensitive without extension), which is searched within
CMAKE_MODULE_PATH. This makes it easy to specify the devkitPro platform a given project targets directly by name,
e.g. 3DS, Switch, WiiU, etc.
Catnip-laced projects declare their own layout and contents using CMake scripts processed in script mode.
The root directory of the project must contain a Catnip script, as well as every subdirectory that is added by it.
The Catnip script can be a file called Catnip.cmake, or alternatively CMakeLists.txt can be reused for this purpose.
In order to allow the directory to be detected as a Catnip-laced project instead of a pure CMake project, a call to the
catnip_package command must appear somewhere within CMakeLists.txt. For example:
cmake_minimum_required(VERSION 3.13)
if(CATNIP) # CATNIP is defined/true if and only if this file is being processed as a Catnip script
catnip_package(MyPackage)
# ... etc ...
return() # Stop processing this file and ignore everything after this point
endif()
# The rest of the CMake code of the project goes here
project(MyProject)
# ... etc ...catnip [<options>] [<verb>] [<selector1> <selector2>...]build(Default): Builds the project. This operation corresponds tomake. The-foption can be specified to trigger a rebuild (similar tomake clean && make).clean: Cleans built intermediate files and artifacts. This operation corresponds tomake clean. Note that the buildsystems generated by CMake aren't deleted by default -- use the-foption to remove them as well.install: Builds the project and installs artifacts. This operation corresponds tomake install. Dependencies of the specified selectors are built as well, but not installed. The-foption is supported, as inbuild.
-S <path-to-root>: Manually specifies the path to the Catnip source root directory.-B <path-to-build>: Manually specifies the path to the Catnip build folder.-D <var>:<type>=<value>, -D <var>=<value>: Adds a CMake cache entry to the current Catnip build folder.-U <var>: Removes a CMake cache entry from the current Catnip build folder. Note: unlike the corresponding CMake command line argument, Catnip does not support globbing.-T <toolset>: Specifies the default toolset used to configure and build projects. This option is saved in the Catnip build folder's default CMake cache, which means it only needs to be specified during the first build of a project.-p: Enables package selector mode -- see below for more information.-v: Enables verbose mode. When this option is specified; CMake configuration logs, as well as the full command line used to invoke tools, will be displayed on screen.-f: Enables forceful mode -- see the Verbs section.
By default, selectors specified in the command line refer to presets (e.g. release, debug) belonging to
the package defined in the current working directory (or the main package in the case of pure CMake projects).
Specify one or more preset names, or all to operate on all presets of the current package. If no presets are selected,
Catnip will automatically choose the default preset(s) of the current package.
If package selector mode (-p) is enabled, selectors will instead have the following format, which allows for selecting any
presets belonging to any arbitrary packages. Unlike in the default mode, at least one selector must be specified in the command line.
The following selector formats are supported:
all: Selects all presets from all packages<package>: Selects a given package's default preset(s)<package>.all: Selects all presets from a given package<package>.<preset>: Selects a specific preset from a given package
