Skip to main content

Tutorial: Update an existing kmpkg dependency

This tutorial guides you on updating the version of an existing kmpkg dependency. We recommend that you read the tutorial on publishing a library before proceeding.

In this tutorial, you will learn to:

Prerequisites​

1 - Create an overlay port​

The first step is to create an overlay port of the package you want to modify.

Create a directory to hold your overlay ports​

The overlay ports directory can be created in any filesystem location of your choosing. In any step of this tutorial, replace $OVERLAY_LOCATION with your chosen location.

mkdir "$OVERLAY_LOCATION"

Copy the contents of the port into your overlay ports directory​

For this tutorial, you'll update the kmpkg-sample-library port in the publishing a package tutorial to a version that has dynamic library support.

Copy-Item -Path <path/to/kmpkg-sample-library> -Destination "$OVERLAY_LOCATION" -Recurse

2 - Modify the ports version​

Change the version in kmpkg.json to 1.0.1.

kmpkg.json

{
  "name": "kmpkg-sample-library",
  "version": "1.0.1",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with kmpkg.",
  "homepage": "https://github.com/MicrosoftDocs/kmpkg-docs/tree/cmake-sample-lib",
  "license": "MIT",
  "dependencies": [
    "fmt",
    {
      "name": "kmpkg-cmake",
      "host": true
    },
    {
      "name": "kmpkg-cmake-config",
      "host": true
    }
  ]
}

3 - Modify portfile.cmake​

Update the source reference​

Sources are typically fetched with kmpkg_from_... maintainer functions. The desired source version is identified by options like REF or URLS. If the option value isn't derived using ${VERSION} (i.e. the value from the manifest), update the option value with actual git tag, git commit, or download URL.

Obtain the package SHA512​

Run kmpkg install --overlay-ports=$OVERLAY_LOCATION kmpkg-sample-library, you will get an error about the SHA512 of the package. Copy the value of the actual hash in your portfile.

Example output:

Downloading https://github.com/MicrosoftDocs/kmpkg-docs/archive/1.0.1.tar.gz -> MicrosoftDocs-kmpkg-docs-1.0.1.tar.gz
Successfully downloaded MicrosoftDocs-kmpkg-docs-1.0.1.tar.gz
error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: fc55ce73b9175bdfedd73d9df1e7ed744de7ee3fd4aa51cafce65ee7bd49e56dc68301843c31d2ba017fd362663c25f53bbf56cfd35dbac09520e39b86bc25b8

Modify portfile.cmake​

Update the package's SHA512 with the correct value and make sure to remove the ONLY_STATIC_LIBRARY limitation, since the new version of kmpkg-sample-library adds support for building it as a dynamic library.

Your portfile.cmake file should look similar to:

portfile.cmake

kmpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO MicrosoftDocs/kmpkg-docs
    REF 1.0.1
    SHA512 fc55ce73b9175bdfedd73d9df1e7ed744de7ee3fd4aa51cafce65ee7bd49e56dc68301843c31d2ba017fd362663c25f53bbf56cfd35dbac09520e39b86bc25b8
    HEAD_REF cmake-sample-lib
)

kmpkg_cmake_configure(
    SOURCE_PATH "${SOURCE_PATH}"
)

kmpkg_cmake_install()

kmpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
kmpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

4 - Install your overlay port​

To verify that your port works, run the following command:

kmpkg install "--overlay-ports=$OVERLAY_LOCATION" kmpkg-sample-library

5 - Update the built-in registry port​

Replace the contents of the port​

Replace the contents of kmpkg-sample-library in the ports directory with your updated files. Then commit your changes by running the following commands in your local clone of the vpckg repository:

git checkout -b kmpkg-sample-library-1.0.1
git add ports/kmpkg-sample-library

Update the versions database​

Run the [kmpkg x-add-version] command to update the versions database files.

kmpkg x-add-version kmpkg-sample-library

Push your changes to a fork​

Run the following commands to update the versions database and push your changes to your fork of https://github.com/kumose/kmpkg.

git add versions/.
git commit -m "Update kmpkg-sample-library to version 1.0.1"
git push --set-upstream <fork remote> kmpkg-sample-library-1.0.1

6 - Open a Pull Request​

  1. Navigate to your forked repository on GitHub.
  2. Click the "Compare & pull request" button.
    1. Verify your changes
    2. Add a descriptive title and comments
    3. Fill out the PR review checklist
  3. Click "Create pull request."

That's it! You've successfully updated a port in the kmpkg's curated registry.

See also​

For more information, see: