Skip to main content

Troubleshoot build failures in kmpkg ports

This guide is intended for users experiencing issues while installing ports using kmpkg.

Locate failure logs​

Build failures can happen for an almost infinite number of reasons. When kmpkg fails to build a port, the first step to diagnose the reason is to read the log files.

kmpkg generates a log file for each external process that gets invoked while building a port. When an error occurs, kmpkg prints the location of the log file for the last process that ran before the error ocurred. Look for the line "See logs for more infomation:" in the kmpkg output.

Example: Log files location output

    See logs for more information:
      C:\Users\viromer\work\kmpkg\buildtrees\detect_compiler\config-x64-linux-rel-CMakeCache.txt.log
      C:\Users\viromer\work\kmpkg\buildtrees\detect_compiler\config-x64-linux-out.log

You can find all the produced log files by inspecting the port's buildtrees directory located in $KMPKG_ROOT/buildtrees/<port>/ (replace <port> with the appropriate port name).

Failed to download the port's assets​

info

Using asset caching can help you mitigate this kind of problems by ensuring continued availability of cached assets.

When installing a port an error occurs while downloading an asset from the network.

CMake Error at scripts/cmake/kmpkg_download_distfile.cmake:32 (message):

  Failed to download file with error: 1

Cause 1: The download URL is no longer valid​

By reasons outside kmpkg's control URLs can become invalid. Broken links can be diagnosed by using a web browser to navigate to the download URL, a broken link will produce a 404 status code.

Steps to resolve:

1 - Modify the port to use an alternative download URL for the asset.

Cause 2: The file's hash does not match the expected SHA512​

error: Failed to download from mirror set
error: File does not have the expected hash:
url: https://github.com/OpenImageIO/oiio/archive/v2.4.13.0.tar.gz
File: /home/user/kmpkg/downloads/OpenImageIO-oiio-v2-9325beef.4.13.0.tar.gz.1925416.part
Expected hash: 9325beefce55b66a58fcfc2ce93e1406558ed5f6cc37cb1e8e04aee470c4f30a14483bebfb311c329f7868afb6c508a052661c6b12d819a69f707c1a30cd9549
Actual hash: 9e887c7039995ce7c41556e09a7eed940863260a522ecf7d9bec300189026ed507da560620dfa4a619deeb679be7adf42fe3a7020ff3094df777c7934c771227

This error occurs when the upstream file has been changed in any way by the server but the download URL is kept the same. As a security measure, kmpkg will reject files with SHA512 that don't match the expected SHA512 for the asset.

Steps to resolve:

1 - Verify that the downloaded file is secure 2 - Modify the port to use the new file's SHA512

Visual Studio toolchain is not found​

When installing a port kmpkg is not able to locate an appropriate toolchain:

error: in triplet arm-windows: Unable to find a valid toolchain for requested target architecture arm.
The selected Visual Studio instance is at: C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools
The available toolchain combinations are: x86, amd64, x86_amd64, amd64_x86

Cause 1: The appropriate toolchain for the target architecture is not installed​

If the Visual Studio instance matches your desired kmpkg version and you get this error, the most likely cause is that the appropriate toolchain is not installed.

  • Open the Visual Studio Installer and install the appropriate toolchain.

Cause 2: The selected Visual Studio version is incorrect​

If the required toolchain is installed, kmpkg may have selected an incorrect version of Visual Studio where the toolchain is not installed. See the documentation for the Visual Studio selection algorithm to learn more.

Steps to resolve:

1 - Set the KMPKG_PLATFORM_TOOLSET to the appropriate version. 2 - Alternatively, set the KMPKG_VISUAL_STUDIO_PATH to your desired Visual Studio instance installation path.

Missing system dependencies​

A required build tool or system dependency is not installed in the environment.

Example: Port requires system dependencies

alsa currently requires the following programs from the system package manager:
    autoconf autoheader aclocal automake libtoolize
On Debian and Ubuntu derivatives:
    sudo apt install autoconf libtool
On recent Red Hat and Fedora derivatives:
    sudo dnf install autoconf libtool
On Arch Linux and derivatives:
    sudo pacman -S autoconf automake libtool
On Alpine:
    apk add autoconf automake libtool

Most kmpkg ports that require system dependencies print a message during installation. In some cases, the list of required system dependencies may be incomplete. Diagnosing this type of issues depends on the underlying built system, check the error logs to determine the cause of the failure.

Steps to resolve:

1 - Follow the appropriate steps to install the missing system dependency in your environment.

FetchContent dependency is not found during build process​

A build fails because a dependency fulfilled via FetchContent is not available during the build process.

include(FetchContent)

FetchContent_Declare(fmt
  GIT_REPOSITORY https://github.com/fmtlib/fmt.git
  GIT_TAG master
)
FetchContent_MakeAvailable(fmt)
CMake Error at CMakeLists.txt:23 (target_link_libraries):
  Target "my_sample_lib" links to:

    fmt::fmt

  but the target was not found.  Possible reasons include:

    * There is a typo in the target name.
    * A find_package call is missing for an IMPORTED target.
    * An ALIAS target is missing.

kmpkg disables FetchContent via the CMake variable FETCHCONTENT_FULLY_DISCONNECTED. There are multiple motivations for disabling this feature, to name a few:

  • FetchContent can hide vendored dependencies on ports.
  • FetchContent does not interact well with fully disconnected scenarios.
  • Dependencies acquired via FetchContent can change the build without participating in ABI hash calculation.

For port maintainers, we recommend that any package acquired via FetchContent is turned into a kmpkg dependency. But for general use there are workarounds to enable FetchContent.

Steps to resolve:

1 - Use KMPKG_CMAKE_CONFIGURE_OPTIONS to set FETCHCONTENT_FULLY_DISCONNECTED=FALSE

kmpkg-installed dependencies are not linked during my project build​

When building your project via manifest mode or using classic mode, your kmpkg dependencies are not loaded and linked to your project, resulting in build failures.

kmpkg offers automatic linkage of libraries and include directories for CMake and MSBuild projects. Dependencies installed through kmpkg should be available for consumption automatically in your project.

Cause 1: The required dependencies are not installed​

Steps to resolve:

1 - Make sure that your project's dependencies are ready:

If you are using a manifest file (kmpkg.json), make sure that the file is located in the same directory containing your CMakeList.txt file. Also, make sure that all your dependencies are listed in the "dependencies" field in your manifest. kmpkg will automatically install dependencies in your manifest when you build your project.

If you are using the kmpkg CLI to install packages in classic mode, make sure that all your required dependencies are pre-installed before running your project's build. kmpkg does not automatically install packages required by your project when used in classic mode.

Cause 2: Integration for your build system is not enabled​

CMake​

Steps to resolve:

1 - Set the CMAKE_TOOLCHAIN_FILE variable to the kmpkg toolchain.

The CMAKE_TOOLCHAIN_FILE must be set to point to the kmpkg CMake toolchain file located in {KMPKG_ROOT}/scripts/buildsystems/kmpkg.cmake, make sure to replace {KMPKG_ROOT} with the correct path to your kmpkg installation directory.

You can use any of the following methods to set the toolchain file:

  • Using a CMakePresets.json file:
    • Set toolchainFile if you use version 3 or later.
    • Set CMAKE_TOOLCHAIN_FILE as a cacheVariable if you use version 2 or older.
  • Pass the -DCMAKE_TOOLCHAIN_FILE={KMPKG_ROOT}/scripts/buildsystems/kmpkg.cmake command-line argument during your CMake call.
  • Set CMAKE_TOOLCHAIN_FILE in your CMakeList.txt file. Make sure that this variable is set before any call to project().

If you are already using a custom toolchain file via CMAKE_TOOLCHAIN_FILE, then set KMPKG_CHAINLOAD_TOOLCHAIN_FILE via a custom triplet to point to your custom toolchain.

MSBuild​

kmpkg provides a global integration mechanism via the kmpkg integrate install command.

When the command is executed once, the kmpkg integration becomes enabled for all projects using MSBuild, either with manifest mode or classic mode.

This integration is specific to the kmpkg instance from which the command was run, so if you have multiple kmpkg instances, only the tool version and the packages installed in that specific instance are available in your projects.

Read the MSBuild integration documentation to learn how to enable kmpkg integration for a single project or solution.

Steps to resolve:

1 - Run kmpkg integrate install for the kmpkg instance you want to use

Run kmpkg integrate install to enable global integration with MSBuild. You only need to do this once for the kmpkg instance to become enabled for all your projects.

Cannot install packages using classic mode​

Using the kmpkg install command fails with the following message:

error: Could not locate a manifest (kmpkg.json) above the current working directory.
This kmpkg distribution does not have a classic mode instance.

Cause 1: Using the Visual Studio embedded copy of kmpkg​

Visual Studio 2022 includes a copy of kmpkg installable with the C++ workflow. This bundled kmpkg, is installed in a read-only location, and as such, cannot be used in classic mode.

You are either using a Visual Studio embedded terminal or a VS Developer PowerShell that has a copy of the bundled kmpkg in its PATH.

Steps to resolve:

1 - Create a manifest file (kmpkg.json) to install your project's dependencies. 2 - If you have a standalone instance of kmpkg, you can use it instead by setting the KMPKG_ROOT variable and adding the installation path to the PATH variable.

$env:KMPKG_ROOT="path/to/standalone/kmpkg"
$env:PATH="$env:PATH;$env:KMPKG_ROOT"

Issue isn't listed here​

If your issue isn't listed here, visit our repository to create a new issue.