vcpkg

vcpkg Integration in imodel-native

All vcpkg documentation for humans lives in iModelCore/libsrc/VCPKG.md. This skill summarises the patterns an agent needs to get the build wiring right.

The Sequential Install Chain

All vcpkg install calls run through a single sequential chain defined in iModelCore/libsrc/vcpkg.PartFile.xml. The chain currently is:

vcpkg (bootstrap)
  └─► vcpkg_install_compress
        └─► vcpkg_install_png
              └─► vcpkg_install_openssl
                    └─► vcpkg_install_crashpad

Each link is a separate Part with its own vcpkg_install_<consumer>.mke that calls vcpkg_run_install.bat / vcpkg_run_install.sh. Chaining ensures no two vcpkg processes ever run concurrently — concurrent runs against the same install root collide on vcpkg-running.lock and corrupt the build.

Consumer .mke files do NOT call vcpkg_run_install themselves. By the time a consumer .mke runs, its install is already complete.

Adding a New vcpkg Library

Always update iModelCore/libsrc/README.md — add a row to the library table with the directory, library name, version, and Yes in the vcpkg column.

1. Create the manifest directory

Under iModelCore/libsrc/<mylib>/:

• vcpkg.json — list dependency with version>= under dependencies and exact version under overrides
• vcpkg-configuration.json — copy from an existing consumer (e.g. compress/); update baseline if needed
• triplets/ — platform-specific triplet files if the defaults in iModelCore/libsrc/ are not sufficient (see compress/triplets/ for examples)

2. Create iModelCore/libsrc/vcpkg_install_<mylib>.mke

%include mdl.mki

mylibDir    = $(_MakeFilePath)<mylib>/
installRoot = $(OutputRootDir)vcpkg_installed/<mylib>/

# Add vcpkgWindowsMDCRT = 1 here if the library must link /MD on Windows (like openssl).
# Add vcpkgUseVeracodeTriplet = 1 here ONLY if this library's base triplet sets explicit
# -RTC flags and you have provided a triplets/x64-windows-static-veracode.cmake overlay
# that omits them (see compress/ and crashpad/). Libraries whose triplets set no -RTC
# flags need no veracode variant and should leave this undefined.
%include $(_MakeFilePath)vcpkg.mki

always:
%if defined (winNT)
    $(_MakeFilePath)vcpkg_run_install.bat $(mylibDir) $(installRoot) $(vcpkgTriplet)
%else
    $(_MakeFilePath)vcpkg_run_install.sh $(mylibDir) $(installRoot) $(vcpkgTriplet)
%endif

$(_MakeFilePath) resolves to libsrc/ because the file lives there, so the paths to <mylib>/, vcpkg_run_install.bat/sh, and vcpkg.mki are all correct.

3. Extend the chain in iModelCore/libsrc/vcpkg.PartFile.xml

Insert a new link into the chain. Appending at the end is the simplest choice, but the chain only needs to stay linear — where a link sits does not affect correctness because every consumer depends on its own named part. Prefer placing a more basic/foundational library (e.g. a compression or image codec that other libraries build on) earlier in the chain, and insert a new link wherever it reads most naturally alongside its peers.

To append at the end (after the current last link):

<Part Name="vcpkg_install_<mylib>" BentleyBuildMakeFile="vcpkg_install_<mylib>.mke">
    <SubPart PartName="vcpkg_install_<current-last>" LibType="Static"/>
</Part>

To insert mid-chain, point the new part at its predecessor and re-parent the following link onto the new part, keeping the chain linear. Whichever position you choose, update the sibling .mke comment ("Runs after vcpkg_install_<prev>…") on every link whose predecessor changed.

4. Wire the consumer PartFile

In your library's .PartFile.xml, depend on the chain part with LibType="Static".

Critical: $(OutputRootDir) differs between static and dynamic builds (static/vcpkg_installed/… vs vcpkg_installed/…). The chain always runs static-only; dynamic builds do not run vcpkg install at all — their .mke reads the packages the static chain produced under static/vcpkg_installed/… (see step 5). Using LibType="Static" here ensures the static chain completes (and populates that install root) before a dynamic build starts, without triggering a redundant dynamic chain build that would race against the static one on the shared vcpkg git repo.

<Part Name="MyLib" BentleyBuildMakeFile="MyLib.mke">
    <!-- LibType="Static": chain is static-only.  Dynamic builds read the packages from the
         static install root; they do not run vcpkg themselves (see step 5). -->
    <SubPart PartName="vcpkg_install_<mylib>" PartFile="iModelCore/libsrc/vcpkg" LibType="Static"/>
    ...

If a separate prewire/PublicAPI part also needs the install, give it the same LibType="Static" SubPart (see BeOpenSSL.PartFile.xml for the __PublicAPI example).

5. Write the consumer .mke

Include vcpkg.mki to get vcpkgTriplet, then set vcpkgInstallRoot.

Key rule: the chain always runs as Static, so the installed packages always live under the static OutputRootDir. Dynamic builds must redirect vcpkgInstallRoot to that same static location — do not call vcpkg_run_install from the dynamic .mke path, because this creates a concurrent vcpkg process that races against the static chain on shared global locks (registry git lock, cmake download rename, etc.).

Use CREATE_STATIC_LIBRARIES (defined by bmake for static builds) to pick the right root:

# Static builds: packages are at $(OutputRootDir)vcpkg_installed/<mylib>/
# Dynamic builds: chain ran as Static; redirect to the same location.
%if defined (CREATE_STATIC_LIBRARIES)
vcpkgInstallRoot = $(OutputRootDir)vcpkg_installed/<mylib>/
%else
vcpkgInstallRoot = $(OutputRootDir)static/vcpkg_installed/<mylib>/
%endif
vcpkgTripletDir  = $(vcpkgInstallRoot)$(vcpkgTriplet)/
vcpkgIncludeDir  = $(vcpkgTripletDir)include/
vcpkgLibDir      = $(vcpkgTripletDir)lib/

No vcpkg_run_install call in the .mke at all — the chain part handles it.

Libraries that only build as static (e.g. compress, crashpad client) can skip the %if defined (CREATE_STATIC_LIBRARIES) conditional and use $(OutputRootDir)vcpkg_installed/… directly — their OutputRootDir is always the static one.

6. Migrating an existing (previously vendored) library

When the library you are moving to vcpkg was previously vendored (its source checked into iModelCore/libsrc/<mylib>/), the vendored source deletion belongs in the same PR as the vcpkg wiring, but do not delete it up front. Keep the vendored source in place (the PR will likely be draft/WIP at this stage) until after the PR has passed its Copilot review, then remove the vendored code in a separate standalone commit within that same PR. Deleting the vendored source up front produces too many modified files for Copilot to review, and the review may not run at all.

Updating an Existing Library Version

Always update iModelCore/libsrc/README.md — bump the version in the library table to match the new version in vcpkg.json.

1. Edit iModelCore/libsrc/<consumer>/vcpkg.json:
   • Update the version>= value under dependencies
   • Update the matching entry in overrides
2. If the new version requires a newer port registry, update baseline in iModelCore/libsrc/<consumer>/vcpkg-configuration.json.
3. No changes to .mke or .PartFile.xml files are needed — the next build will pick up the new version via the binary cache or a fresh build.

Triplet Selection (vcpkg.mki)

iModelCore/libsrc/vcpkg.mki maps TARGET_PROCESSOR_ARCHITECTURE to vcpkgTriplet:

Key Files