Package Management (Experimental)

Camp’s package infrastructure is a development-preview compiler feature. It exists so compiler authors can exercise package API generation, native artifact caching, package references, restore behavior, publishing, and language-service integration while the package model is still settling.

Packages are source-only payloads. A package source publishes deterministic zip archives plus a versions.ini catalog. Projects restore selected archives into their local package cache and record exact selections in packages.ini. Ordinary build, run, test, cover, dump, and language-server operations consume only installed package cache entries. They do not contact package sources and do not use --use-source as a live source lookup path.

Dependency Specs

Package dependencies use a package name, an optional version request, and an optional link kind:

textlib
textlib@1
textlib@1.2
textlib@1.2.0
textlib/1.2.0
textlib@1.2.0:shared
textlib:static
textlib:api

@ requests a compatible catalog version. pkg@1 means any 1.x.y version, pkg@1.2 means any 1.2.y version, and pkg@1.2.0 means that exact selected version. / names an exact installed version.

The default dependency link kind is :shared.

Package Sources

--use-source <name> <path-or-url> declares a named package source for restore, install, and publish workflows:

#build --use-source local-libs ../packages
#build --use textlib@1.2

The source path can be a local filesystem path or an HTTP/HTTPS URL. Source names are local configuration. They are not written to packages.ini.

A source root contains package directories:

packages/
  textlib/
    versions.ini
    textlib_1.2.0.zip

versions.ini describes package identity, published versions, source archives, hashes, compiler provenance, and direct dependencies:

[package]
name=textlib
identity=textlib

[1.2.0]
compiler=campc/0.9.1-preview.1
use=otherlib@1:static
sha256=<archive-sha256>
src=textlib_1.2.0.zip

Archive paths are relative to the package directory unless they are already absolute paths or URLs.

Restore And Lock Files

campc restore reads effective --use-source and --use declarations from the provided source/build file plus compiler-root package source configuration. It resolves direct and transitive dependencies, verifies archive SHA-256 values, extracts selected source archives into the project cache, and writes packages.ini:

campc restore textapp.campbuild
campc restore src/*.camp
campc restore --only-local

If no target is specified, restore can select the only .campbuild file in the current directory when there are no loose .camp source files. --only-local ignores compiler-root base.campbuild and global.campbuild package sources.

The lock file records portable package facts only:

[textlib]
identity=textlib
version=1.2.0
sha256=<archive-sha256>

Restore reuses locked versions unless --upgrade is supplied. --upgrade updates all direct dependencies. --upgrade textlib updates one direct dependency, and --upgrade textlib@1.3 updates it within the supplied version request.

Installed Package Cache

Restored and manually installed packages use:

<project>/cache/pkg/<package>/<version>/
<compiler-home>/cache/pkg/<package>/<version>/

Project cache entries win over compiler/global cache entries. A restored package contains the extracted source archive:

cache/pkg/
  textlib/
    1.2.0/
      src/
        text.camp
      textlib.campbuild

Package API/native artifacts are built lazily under the installed package version:

cache/pkg/textlib/1.2.0/bin/<artifact-directory>/
  textlib_api.camp
  textlib_api.h
  textlib_api.json
  libtextlib.a

Dependency Link Kinds

Package dependencies support three link kinds:

When the root request does not build a native artifact, package preparation only needs API headers. When the root request builds an executable or library, :static and :shared request native libraries, while :api deliberately does not.

Package Commands

campc package commands are development-preview commands.

The target is either --global, an explicit .campbuild or .camp file, or the implicit single .campbuild in the current directory. install and uninstall alter only package caches and print that project configuration was not changed.

Publishing

package publish selects a build file, collects package source files, creates a deterministic source zip, computes its SHA-256, and writes or updates versions.ini. The default output directory is:

<project-root>/pub/<package-name>/

--pub-dir names the publication root directory. Package files are written under <pub-dir>/<package-name>/.

Published archives exclude generated outputs, package caches, build caches, lock files, and binary artifacts.

Standard Library Package

The standard library is still compiler-owned. Unless --nostdlib is set, the compiler prepares package std from lib/std/src and caches its artifacts under the compiler library cache. User package restore does not route std through packages.ini.

Project References Versus Packages

Use a project reference when the dependency is another project in the same source tree and should be built with the consumer’s target, profile, variants, and requested link kind. Use package references when the dependency should be resolved through restore and consumed from the package cache.

Project references accept only :static and :shared suffixes. Package references also accept :api.

Cache Validity

Package cache reuse is conservative. The compiler compares output timestamps against source files, native helper sources, headers, target definitions, and compiler inputs. Command-line configuration that can change output disables cache reuse for that request.

Delete a package version’s bin directory to force artifact rebuild for one target/profile/link kind. Delete the package version directory to force reinstallation by campc restore or campc package install.