XMSConan

Methods and Modules used to aid in xmsconan projects.

Installation

pip install xmsconan

Usage

This package provides tools for building and generating files for XMS projects using Conan.

Unified CLI

All tools are available under the xmsconan command:

xmsconan <command> [args...]
xmsconan --help              # list all commands
xmsconan gen --help          # help for a specific command

Legacy entry points (xmsconan_gen, xmsconan_ci, xmsconan_build, etc.) remain available for backwards compatibility.

build.toml Schema Reference

The build.toml file defines the structure and dependencies of your XMS library. All fields are optional unless marked as required.

Required Fields

Source Files

Dependencies

Build Configuration

Advanced

Example build.toml

library_name = "xmscore"
description = "Support library for XMS products"

xms_dependencies = []

python_namespaced_dir = "core"
pybind_root = true

library_sources = [
    "xmscore/math/math.cpp",
    "xmscore/misc/StringUtil.cpp",
]

library_headers = [
    "xmscore/math/math.h",
    "xmscore/misc/StringUtil.h",
]

testing_sources = [
    "xmscore/testing/TestTools.cpp"
]

testing_headers = [
    "xmscore/math/math.t.h",
    "xmscore/testing/TestTools.h",
]

pybind_sources = [
    "xmscore/python/xmscore_py.cpp",
]

Example generation

xmsconan gen --version 9.0.0 build.toml

Example generation dry-run

xmsconan gen --dry-run -v --version 9.0.0 build.toml

Example build into a shared builds folder

xmsconan build --cmake_dir . --build_dir ../builds/xmscore --profile VS2022_TESTING --generator vs2022

Example build dry-run

xmsconan build --cmake_dir . --build_dir ../builds/xmscore --profile VS2022_TESTING --generator vs2022 --dry-run -v

Useful build flags

• --allow-missing-test-files: Continue when test data path is missing
• --dry-run: Print Conan/CMake commands and options without executing
• -v / -q: Increase debug output or suppress informational logs

CI Tools

These commands replace inline shell scripts in CI templates, reducing duplication and making pipelines easier to maintain.

Conan Setup

# Default: detect profile, add Aquaveo remote
xmsconan conan-setup

# GitHub Actions: also login and remove conancenter
xmsconan conan-setup --remote-url https://conan2.aquaveo.com/... --login --remove-conancenter

Wheel Repair

# Auto-detect platform and repair wheels in wheelhouse/
xmsconan wheel-repair --wheel-dir wheelhouse

# Explicit platform
xmsconan wheel-repair --wheel-dir wheelhouse --platform macos

Wheel Deploy

# Uses $AQUAPI_URL, $AQUAPI_USERNAME, $AQUAPI_PASSWORD env vars
xmsconan wheel-deploy --wheel-dir wheelhouse

# Or pass credentials explicitly
xmsconan wheel-deploy --wheel-dir wheelhouse --url https://... --username user --password pass

Conan Deploy

# Save a package to a tarball
xmsconan conan-deploy xmscore 7.0.0 --save xmscore-7.0.0.tar.gz

# Restore and upload
xmsconan conan-deploy xmscore 7.0.0 --restore xmscore-7.0.0.tar.gz --upload

Building with Docker

XMS C++ libraries can be built inside Docker containers for Linux. This is the recommended approach for producing Linux wheels and Conan packages from macOS or Windows.

Prerequisites

The workspace docker-compose.dev.yml provides two dev containers:

Start the container you need:

# From the workspace root (aqua_dev/)
docker compose -f docker-compose.dev.yml up dev-arm -d   # ARM (fast on Apple Silicon)
docker compose -f docker-compose.dev.yml up dev-x86 -d   # x86_64 (matches CI)

Credential Setup

Create ~/.xmsconan.toml on your host machine to avoid passing credentials on every build:

[aquapi]
url = "https://public.aquapi.aquaveo.com/aquaveo/dev/"
username = "your_username"
password = "your_password"

Mount it into the container by adding a volume to docker-compose.dev.yml:

volumes:
  - ~/.xmsconan.toml:/root/.xmsconan.toml:ro

Alternatively, pass credentials as environment variables:

docker exec -e AQUAPI_URL=https://public.aquapi.aquaveo.com/aquaveo/dev/ \
            -e AQUAPI_USERNAME=user \
            -e AQUAPI_PASSWORD=pass \
            nextms-dev-arm bash -c "cd /workspace/xmscore && xmsconan publish --version 7.0.0"

Building a Single Library

# Full build + upload (reads credentials from ~/.xmsconan.toml or env vars)
docker exec nextms-dev-arm bash -c "cd /workspace/xmscore && xmsconan publish --version 7.0.0"

# Build and repair wheel only, skip uploads
docker exec nextms-dev-arm bash -c "cd /workspace/xmscore && xmsconan publish --version 7.0.0 --no-deploy"

# Upload wheel only, skip Conan package
docker exec nextms-dev-arm bash -c "cd /workspace/xmscore && xmsconan publish --version 7.0.0 --no-conan"

# Filter to Release builds only
docker exec nextms-dev-arm bash -c "cd /workspace/xmscore && xmsconan publish --version 7.0.0 --filter '{\"build_type\": \"Release\"}'"

Building Libraries in Dependency Order

Libraries must be built in dependency order so Conan packages are available for downstream builds:

xmscore → xmsgrid → xmsinterp → xmsmesher
                               → xmsextractor → xmsconstraint
xmscore → xmsvtk

Example for a full ARM build:

CONTAINER=nextms-dev-arm
VERSION=7.0.0

docker exec $CONTAINER bash -c "cd /workspace/xmscore && xmsconan publish --version $VERSION --no-deploy"
docker exec $CONTAINER bash -c "cd /workspace/xmsgrid && xmsconan publish --version $VERSION --no-deploy"
docker exec $CONTAINER bash -c "cd /workspace/xmsinterp && xmsconan publish --version $VERSION --no-deploy"
docker exec $CONTAINER bash -c "cd /workspace/xmsmesher && xmsconan publish --version $VERSION --no-deploy"
docker exec $CONTAINER bash -c "cd /workspace/xmsextractor && xmsconan publish --version $VERSION --no-deploy"
docker exec $CONTAINER bash -c "cd /workspace/xmsconstraint && xmsconan publish --version $VERSION --no-deploy"

Replace --no-deploy with no flag to also upload each package as it's built.

macOS vs. Windows

On Windows, use nextms-dev-x86 for x86_64 Linux builds. The commands are identical — just change the container name.

License

BSD 2-Clause License