Skip to main content

What is manifest mode?

kmpkg has two operation modes: classic mode and manifest mode. For most users, we recommend manifest mode.

Manifest mode uses declarative JSON files to describe metadata about your project or package. Manifest files are required to have the kmpkg.json name.

Manifest mode is engaged by running the kmpkg install command while there's a manifest file (kmpkg.json) in the working directory. Read ahead for details on how to install packages in manifest mode.

Manifest mode is also required to use advanced features like versioning and custom registries.

Manifest files in ports​

All kmpkg ports must include a kmpkg.json file that describes metadata about the package they install.

kmpkg uses the metadata in the package manifest for various purposes, such as, calculating dependency trees, searching for packages by name or description, resolving features, etc.

Package manifest example​

{
  "name": "fmt",
  "version": "10.1.1",
  "description": "Formatting library for C++. It can be used as a safe alternative to printf or as a fast alternative to IOStreams.",
  "homepage": "https://github.com/fmtlib/fmt",
  "license": "MIT",
  "dependencies": [
    {
      "name": "kmpkg-cmake",
      "host": true
    },
    {
      "name": "kmpkg-cmake-config",
      "host": true
    }
  ]
}

Manifest files in projects​

The main purpose of using a manifest file in your project is to declare your dependencies. When using a project manifest, you're able to specify version constraints and overrides to lock specific versions of your dependencies. This feature is not available in classic mode.

Project manifest example​

{
  "dependencies": [ "fmt", "zlib" ],
  "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
  "overrides": [
    { "name": "zlib", "version": "1.2.8" }
  ]
}

Configuration file​

kmpkg can be configured through a kmpkg-configuration.json file to add more package registries or overlay ports and triplets locations.

Configuration file example​

{
  "default-registry": {
    "kind": "git",
    "baseline": "7476f0d4e77d3333fbb249657df8251c28c4faae",
    "repository": "https://github.com/kumose/kmpkg"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/MicrosoftDocs/kmpkg-docs",
      "reference": "kmpkg-registry",
      "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
      "packages": [ "beicode", "beison" ]
    }
  ],
  "overlay-ports": [
    "C:\\dev\\my_kmpkg_ports"
  ]
}

Installing packages in manifest mode​

To install packages using a manifest file you use the kmpkg install command without any package arguments. The command must be executed from a directory containing a manifest kmpkg.json file, or the path to a manifest file provided by using the --x-manifest-root=<path> option.

Packages installed in manifest mode will not be installed in the global installed directory as they do in classic mode. Instead, each manifest gets its own installation directory named kmpkg_installed; the kmpkg_installed directory is created in the same directory that contains the manifest file.

Having independent installation trees per manifest allows separation of dependencies between different projects. This circumvents a crucial limitation of classic mode, which only allows one version of each port to be installed. Manifest mode keeps versions of ports separated per project.

Using features in project manifests​

Manifest files can define additive sets of functionality, behavior, and dependencies through the use of "features".

In your projects, you may define features to enable or disable dependencies that apply to parts of your project. For example, if your project contains multiple components, you may want to keep common dependencies in the "dependencies" list but limit some others to their respective components.

To enable features of your project you can use one of the following methods:

Example: Features in project manifests​

{
  "name": "my-game",
  "dependencies": [ "grpc" ],
  "features": {
    "client": {
      "description": "client game executable",
      "dependencies": [ "sdl2", "bullet3" ]
    },
    "server": {
      "description": "multiplayer server executable",
      "dependencies": [ "proxygen" ]
    },
    "tests": {
      "description": "development tests",
      "dependencies": [ "gtest" ]
    }
  }
}

To build only the "client" component's dependencies run:

kmpkg install --x-feature=client

Next steps​

Here are some tasks to try next: