https://github.com/devkitpro/catnip

devkitPro CMake helper tool
https://github.com/devkitpro/catnip

Last synced: 11 months ago
JSON representation

devkitPro CMake helper tool

• Host: GitHub
• URL: https://github.com/devkitpro/catnip
• Owner: devkitPro
• Created: 2024-04-24T17:08:42.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2024-12-30T15:22:30.000Z (about 1 year ago)
• Last Synced: 2025-01-13T09:45:44.435Z (about 1 year ago)
• Language: CMake
• Homepage:
• Size: 26.4 KB
• Stars: 7
• Watchers: 2
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# `catnip` Manual

> *"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.

## Concepts

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 `), 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 `/build`, although it can be explicitly set in

the command line (`-B `) or with an environment variable (`CATNIP_BUILD_DIR`).

The build folder contains multiple subfolders named `.`, 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

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 ...

```

## Command-line usage

```bash

catnip [] [] [ ...]

```

### Verbs

- `build` *(Default)*: Builds the project. This operation corresponds to `make`. The `-f` option can be specified to trigger a rebuild (similar to `make clean && make`).

- `clean`: Cleans built intermediate files and artifacts. This operation corresponds to `make clean`. Note that the buildsystems generated by CMake aren't deleted by default -- use the `-f` option to remove them as well.

- `install`: Builds the project and installs artifacts. This operation corresponds to `make install`. Dependencies of the specified selectors are built as well, but not installed. The `-f` option is supported, as in `build`.

### Options

- `-S `: Manually specifies the path to the Catnip source root directory.

- `-B `: Manually specifies the path to the Catnip build folder.

- `-D :=, -D =`: Adds a CMake cache entry to the current Catnip build folder.

- `-U `: 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 `: 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.

### Selectors

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

- ``:          Selects a given package's default preset(s)

- `.all`:      Selects all presets from a given package

- `.`: Selects a specific preset from a given package