Skip to main content

Tutorial: Install a dependency from the command line

info

See "Install a dependency from a manifest file" for the recommended method of installing your dependencies.

warning

Some kmpkg features are not available in classic mode.

kmpkg has two operation modes: classic mode, and manifest mode. This article describes how to install packages using classic mode. For most users we recommend using manifest mode instead.

In classic mode, you use kmpkg as a command-line interface to install your dependencies in a common installation directory. Usually, located in %KMPKG_ROOT%/installed, where %KMPKG_ROOT% is the kmpkg's installation directory.

Prerequisites​

  • kmpkg
  • A terminal
  • A code editor
  • A C++ compiler
  • (Optional) CMake or MSBuild

1 - Create a project​

In a new folder, create a source file named main.cxx with these contents:

#include <cxxopts.hpp>
#include <fmt/format.h>
#include <range/v3/view.hpp>

namespace view = ranges::views;

int fib(int x)
{
  int a = 0, b = 1;

  for (int it : view::repeat(0) | view::take(x))
  {
    (void)it;
    int tmp = a;
    a += b;
    b = tmp;
  }

  return a;
}

int main(int argc, char **argv)
{
  cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'");
  options.add_options()("n,value", "The value to print to", cxxopts::value<int>()->default_value("10"));

  auto result = options.parse(argc, argv);
  auto n = result["value"].as<int>();

  for (int x : view::iota(1) | view::take(n))
  {
    fmt::print("fib({}) = {}\n", x, fib(x));
  }
}

The code references the open-source libraries: cxxopts, fmt, and range-v3; which are all available in the kmpkg public registry at https://github.com/kumose/kmpkg.

2 - Integrate kmpkg with your build system​

In this step we show you how to integrate kmpkg with CMake or MSBuild, so that your project dependencies get automatically installed or restored whenever you build the project.

If you're using a different build system, skip to the next step: [Install dependencies].

MSBuild​

Learn more about using kmpkg from MSBuild

To use kmpkg in your MSBuild projects, run the following command:

kmpkg integrate install

You only need to run the kmpkg integrate install command the first time you want to enable MSBuild integration. This enables MSBuild integration for all your existing and future projects. Use kmpkg integrate remove to remove MSBuild system-wide integration.

This integration method automatically adds kmpkg-installed packages to the following project properties: Include Directories, Link Directories, and Link Libraries. Additionally, this creates a post-build action that ensures that any required DLLs are copied into the build output folder. This works for all solutions and projects using Visual Studio 2015 or newer.

​

Learn more about using kmpkg from CMake

To use kmpkg in your CMake projects, you need to set the CMAKE_TOOLCHAIN_FILE variable to use kmpkg's CMake toolchain file. The kmpkg toolchain is in %KMPKG_ROOT%/scripts/buildsystems/kmpkg.cmake, where %KMPKG_ROOT% is your kmpkg installation path.

To set the toolchain file use any of these methods:

  • Set the CMAKE_TOOLCHAIN_FILE in your CMakePresets.json file.
  • Pass -DCMAKE_TOOLCHAIN_FILE=<path/to/kmpkg>/scripts/buildsystems/kmpkg.cmake as a parameter in your CMake configure call.
  • Set the CMAKE_TOOLCHAIN_FILE CMake variable before the first call to project() in your CMakeLists.txt file.

3 - Install dependencies​

The code references the open-source libraries: cxxopts, fmt, and range-v3; these are all available in the kmpkg public registry at https://github.com/kumose/kmpkg.

To install these packages use the kmpkg install command.

kmpkg install cxxopts fmt range-v3
$ ./kmpkg install cxxopts fmt range-v3
Computing installation plan...
The following packages will be built and installed:
    cxxopts:x64-windows -> 3.1.1
    fmt:x64-windows -> 10.0.0
    range-v3:x64-windows -> 0.12.0#1
  * kmpkg-cmake:x64-windows -> 2023-05-04
  * kmpkg-cmake-config:x64-windows -> 2022-02-06#1
Additional packages (*) will be modified to complete this operation.
(omitted)
cxxopts provides CMake targets:

    # this is heuristically generated, and may not be correct
    find_package(cxxopts CONFIG REQUIRED)
    target_link_libraries(main PRIVATE cxxopts::cxxopts)

The package fmt provides CMake targets:

    find_package(fmt CONFIG REQUIRED)
    target_link_libraries(main PRIVATE fmt::fmt)

    # Or use the header-only version
    find_package(fmt CONFIG REQUIRED)
    target_link_libraries(main PRIVATE fmt::fmt-header-only)

range-v3 provides CMake targets:

    # this is heuristically generated, and may not be correct
    find_package(range-v3 CONFIG REQUIRED)
    target_link_libraries(main PRIVATE range-v3::meta range-v3::concepts range-v3::range-v3)

4 - Build the project​

warning

Make sure that the triplet of your installed packages matches your project's configuration. Use x64-windows or x64-windows-static for your 64-bit projects and x86-windows or x86-windows-static for your 32-bit projects.

MSBuild​

With system-wide integration enabled, just run msbuild to build the project:

PS D:\projects\manifest-example> msbuild
MSBuild version 17.7.0-preview-23319-02+6829506b8 for .NET Framework
Build started 8/13/2023 3:07:36 PM.

Project "D:\projects\manifest-example\manifest-example.sln" on node 1 (default targets).
ValidateSolutionConfiguration:
  (omitted)
PrepareForBuild:
  (omitted)
InitializeBuildStatus:
  (omitted)
ComputeStdModulesCompileInputs:
  (omitted)
SetModuleDependencies:
KmpkgTripletSelection:
  Using triplet "x64-windows" from "D:\kmpkg\installed\x64-windows\"
  Using normalized configuration "Debug"
ClCompile:
  (omitted)
Link:
  (omitted)
AppLocalFromInstalled:
  pwsh.exe -ExecutionPolicy Bypass -noprofile -File "D:\kmpkg\scripts\buildsystems\msbuild\applocal.ps1" "D:\projects\manifest-example\x64\Debug\manifest-example.exe"
   "D:\kmpkg\installed\x64-windows\debug\bin" "x64\Debug\manifest-example.tlog\manifest-example.write.1u.tlog" "x64\Debug\kmpkg.applocal.log"
  D:\projects\manifest-example\x64\Debug\fmtd.dll
FinalizeBuildStatus:
  Deleting file "x64\Debug\manifest-example.tlog\unsuccessfulbuild".
  Touching "x64\Debug\manifest-example.tlog\manifest-example.lastbuildstate".
Done Building Project "D:\projects\manifest-example\manifest-example.vcxproj" (default targets).

Done Building Project "D:\projects\manifest-example\manifest-example.sln" (default targets).

Build succeeded.

Visual Studio​

Build the project by right-clicking it in Solution Explorer and selecting Build.

Build started...
1>------ Build started: Project: manifest-example, Configuration: Debug x64 ------
1>main.cxx
1>manifest-example.vcxproj -> D:\projects\manifest-example\x64\Debug\manifest-example.exe
1>Done building project "manifest-example.vcxproj".
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
========== Build started at 3:16 PM and took 18.608 seconds ==========

CMake​

1 - Create a CMakeLists.txt file​

Add the following CMakeLists.txt file in the project folder:

CMakeLists.txt:

CMakeLists.txt
cmake_minimum_required(VERSION 3.15)

project(fibonacci CXX)

find_package(fmt CONFIG REQUIRED)
find_package(range-v3 CONFIG REQUIRED)
find_package(cxxopts CONFIG REQUIRED)

set(CMAKE_CXX_STANDARD 17)

add_executable(fibo main.cxx)

target_link_libraries(fibo
  PRIVATE
    fmt::fmt
    range-v3::range-v3
    cxxopts::cxxopts)

2 - Configure your CMake project​

Run the following command: cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=%KMPKG_ROOT%\scripts\buildsystems\kmpkg.cmake, but substitute %KMPKG_ROOT% with your kmpkg installation path.

PS D:\projects\manifest-example> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:/kmpkg/scripts/buildsystems/kmpkg.cmake
-- Building for: Visual Studio 17 2022
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.25921.
-- The CXX compiler identification is MSVC 19.37.32814.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files/Microsoft Visual Studio/2022/Preview/VC/Tools/MSVC/14.37.32814/bin/Hostx64/x64/cl.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: D:/projects/manifest-example/build

3 - Build the CMake project​

Run the following command to build the project: cmake --build build:

PS D:\projects\manifest-example> cmake --build build
MSBuild version 17.7.0-preview-23319-02+6829506b8 for .NET Framework

  Checking Build System
  Building Custom Rule D:/projects/manifest-example/CMakeLists.txt
  main.cxx
  fibo.vcxproj -> D:\projects\manifest-example\build\Debug\fibo.exe
  Building Custom Rule D:/projects/manifest-example/CMakeLists.txt

Next Steps​

In this tutorial, you installed dependencies for a simple project using kmpkg as a command-line interface.

Here are some additional tasks to try next: