pixi.toml

# pixi.toml: Project configuration for the xeus-ocaml Jupyter kernel.
#
# This file defines the project's dependencies, build tasks, and environments.
# It is structured to support both native OCaml development and the compilation
# of the kernel to WebAssembly (WASM) for use in JupyterLite.

###############################################################################
### [workspace]: Core Project Metadata
###############################################################################
[workspace]
# The name of the project.
name = "xeus-ocaml"

# A list of conda channels to search for packages.
# Pixi searches these channels in the specified order.
channels = [
    "https://repo.prefix.dev/emscripten-forge-dev", # Provides Emscripten (WASM) specific packages.
    "conda-forge",
]

# Target platforms for which this project can be built.
platforms = [
    "linux-64",         # For the local development environment and native builds.
    "emscripten-wasm32", # For the WebAssembly version of the kernel.
]


###############################################################################
### Feature Definitions
#
# Features are modular blocks of configuration (e.g., dependencies, tasks)
# that can be combined to create different, isolated environments.
###############################################################################

#==============================================================================
# [feature.ocaml]: Native OCaml Development Environment
# This feature provides the tools and tasks needed for native OCaml
# development, including setting up the OPAM environment and building the
# OCaml source code.
#==============================================================================
[feature.ocaml]
platforms = ["linux-64"]

[feature.ocaml.dependencies]
opam = "*"        # The OCaml Package Manager.
xorg-libx11 = "*" # System dependencies required by some OCaml libraries.
xorg-xproto = "*" # System dependencies required by some OCaml libraries.


[feature.ocaml.tasks]
# Initializes the OPAM environment and installs locked dependencies.
setup = { cmd = """
rm -rf $OPAMROOT && \
opam init --disable-sandboxing --no --compiler=5.3.0 && 
opam install dune && \
opam exec -- dune pkg lock
""", cwd = "ocaml" }

# Cleans the OCaml project build artifacts.
clean = { cmd = "opam exec -- dune clean --root $OCAML_DIR", cwd = "ocaml" }

# Builds the OCaml project (specifically the JavaScript target).
build-dev = { cmd = "opam exec -- dune build --profile dev --root $OCAML_DIR", cwd = "ocaml" }

# Creates a release build of the OCaml project.
build-release = { cmd = "opam exec -- dune build --profile release --root $OCAML_DIR", cwd = "ocaml" }

# Starts a simple Python web server to test the 'playground' example.
playground = { cmd = "python3 -m http.server -d $OCAML_DIR/playground " }


#==============================================================================
# [feature.test]: JavaScript Test Environment
# This feature sets up an environment for running JavaScript-based tests
# using Jest, likely for testing the JavaScript output of the OCaml code.
#==============================================================================
[feature.test]
platforms = ["linux-64"]

[feature.test.dependencies]
# The JavaScript testing framework.
jest = "*"

[feature.test.tasks]
# Installs npm packages and runs the test suite.
test = { cmd = "npm install && jest --runInBand", cwd = "ocaml/tests" }

#==============================================================================
# [feature.extension]: JupyterLab Extension
# Defines the environment and tasks for developing the JupyterLab extension.
# This is intended for a native linux-64 development environment.
#==============================================================================
[feature.extension]
platforms = ["linux-64"]

[feature.extension.dependencies]
# Node.js is required for JupyterLab extension development.
nodejs = "20.*"
# Templating tool used for project scaffolding.
copier = "9.*"
# Jinja2 extension for time-related functions.
jinja2-time = "*"
# Python package installer.
pip = "*"
# The JupyterLab frontend.
jupyterlab = "*"

[feature.extension.tasks]
# Installs Node.js dependencies for the JupyterLab extension.
# It cleans the environment before installing to ensure a fresh state.
setup-extension = { cmd = "truncate -s 0 yarn.lock && rm -rf node_modules && jlpm install", cwd = "extension" }

# Builds the production version of the JupyterLab extension.
# This task depends on 'setup-extension' to ensure dependencies are installed first.
build-extension = { cmd = "jlpm build:prod", cwd = "extension", depends-on = ["setup-extension"] }



#==============================================================================
# [feature.kernel]: WASM Kernel Runtime Environment
# Defines the dependencies for the WebAssembly-based Jupyter kernel.
# This feature is exclusively for the emscripten-wasm32 platform and represents
# the final runtime environment for the kernel inside JupyterLite.
#==============================================================================
[feature.kernel]
platforms = ["emscripten-wasm32"]

[feature.kernel.dependencies]
# The core C++ framework for writing Jupyter kernels.
xeus = "*"


#==============================================================================
# [feature.build]: JupyterLite Build Environment
# Defines the tools and tasks required to build the WASM kernel package
# and assemble the final JupyterLite website.
#==============================================================================
[feature.build]
platforms = ["linux-64"]

[feature.build.dependencies]
# Core dependencies for building and running JupyterLite.
jupyterlab = "*"
#jupyterlite-xeus = "*"
jupyter_server = "*"
ipywidgets = "*"
jupyterlab-myst = "*"
micromamba = "*"
rattler-build = "*"


[feature.build.pypi-dependencies]

jupyterlite-core = { url = "https://github.com/jupyterlite/jupyterlite/releases/download/v0.7.0b0/jupyterlite_core-0.7.0b0-py3-none-any.whl"}
jupyterlite-xeus = { url = "https://github.com/jupyterlite/xeus/releases/download/v4.3.0a3/jupyterlite_xeus-4.3.0a3-py3-none-any.whl" }


[feature.build.tasks]
# Builds the xeus-ocaml WASM kernel as a conda package using a recipe.
# It targets the emscripten-wasm32 platform and uses the necessary channels.
# --no-build-id --keep-build allow caching from one build to another
# remove wasm & js file to make sure they are rebuilt

build-kernel-dev = """
rm -f output/bld/rattler-build_xeus-ocaml/cxx_cache/xocaml.js && \
rm -f output/bld/rattler-build_xeus-ocaml/cxx_cache/xocaml.wasm && \
rattler-build build --recipe recipe/recipe-dev.yaml \
            -c https://repo.prefix.dev/emscripten-forge-4x \
            -c https://repo.prefix.dev/emscripten-forge-dev \
            -c conda-forge \
            --target-platform emscripten-wasm32 \
            --no-build-id \ 
            --keep-build
"""


build-kernel = """
rm -f output/bld/rattler-build_xeus-ocaml/cxx_cache/xocaml.js && \
rm -f output/bld/rattler-build_xeus-ocaml/cxx_cache/xocaml.wasm && \
rattler-build build --recipe recipe/recipe-prod.yaml \
            -c https://repo.prefix.dev/emscripten-forge-dev \
            -c conda-forge \
            --target-platform emscripten-wasm32 \
            --no-build-id \ 
            --keep-build
"""

# Uploads the newly built kernel package to a private prefix.dev channel.
upload-kernel = "rattler-build upload prefix --api-key=$PREFIX_API_KEY -c xeus-ocaml output/emscripten-wasm32/xeus-ocaml*"

# Installs the locally built kernel package into the dedicated 'kernel' environment.
# This makes it available for JupyterLite to bundle.
install-kernel = """
rm -rf .pixi/envs/kernel && \ 
micromamba clean -a -y && \
pixi run -e kernel micromamba install -y --offline --no-channel-priority $PIXI_PROJECT_ROOT/output/emscripten-wasm32/xeus-ocaml*.conda
"""

# Builds the static JupyterLite website.
# It cleans previous build artifacts and points to the WASM kernel
# located in the isolated '.pixi/envs/kernel' directory.
build-jupyterlite = { cmd = "rm -fr _output && rm -f .jupyterlite.doit.db && jupyter lite build --XeusAddon.prefix=.pixi/envs/kernel --contents notebooks" }

# Serves the JupyterLite site locally for development and testing.
# This provides a quick way to test the WASM kernel in a live browser environment.
serve-jupyterlite = { cmd = "python3 -m http.server -d _output/" }

build-all = {depends-on = ["build-kernel","install-kernel", "build-jupyterlite"]}

build-all-dev = {depends-on = ["build-kernel-dev","install-kernel", "build-jupyterlite"]}

build-serve = {depends-on = ["build-all", "serve-jupyterlite"]}

build-serve-dev = {depends-on = ["build-all-dev", "serve-jupyterlite"]}

pre-release = """
rm -rf output && \
pixi run sync-version && \
pixi run build-kernel && \
pixi run test &&\
pixi run install-kernel && \
pixi run build-jupyterlite
pixi run build-docs
"""

#==============================================================================
# [feature.dev-tools]: For developer utilities like the version sync script
#==============================================================================
[feature.dev-tools]
platforms = ["linux-64"]

[feature.dev-tools.dependencies]
'ruamel.yaml' = "*" # For preserving YAML formatting

[feature.dev-tools.tasks]
# Syncs the version from the C++ header to recipe.yaml
sync-version = "python scripts/sync_version.py"

# Verifies that the versions are in sync (for CI)
verify-version = "python scripts/sync_version.py --check"


source-sha = "python scripts/sync_version.py --sha"
#==============================================================================
# [feature.docs]: Documentation Generation Environment
#==============================================================================
[feature.docs]
platforms = ["linux-64"]

[feature.docs.dependencies]
doxygen = "*"
sphinx = "*"
breathe = "*"
opam = "*"
furo = "*"
[feature.docs.tasks]

# Run Doxygen to generate XML from C++ sources
build-docs-cpp = { cmd = "mkdir -p docs/build/doxygen && doxygen docs/doxygen/Doxyfile.in" }

# Run Odoc to generate HTML from OCaml sources
build-docs-ocaml = { cmd = """
opam init --disable-sandboxing --no --compiler=5.4.0 && 
opam install dune && \
opam exec -- dune pkg lock --root ocaml && \
opam exec -- dune build --root ocaml @doc && \
rm -rf _output/docs/odoc && \
mkdir -p _output/docs/odoc && \
cp -r ocaml/_build/default/_doc/_html/* _output/docs/odoc/""" }

# Run Sphinx to build the final website
build-docs-sphinx = { cmd = "sphinx-build -b html docs/source _output/docs"}

# Master task to build all documentation
build-docs = { depends-on = ["build-docs-cpp", "build-docs-ocaml", "build-docs-sphinx"] }

# Serve the generated documentation
serve-docs = { cmd = "python3 -m http.server -d _output/docs/" }


###############################################################################
### [environments]: Environment Definitions
#
# Environments are concrete instances that combine one or more features.
# You can activate an environment using `pixi shell <name>` or run tasks
# within it using `pixi run -e <name> <task>`.
###############################################################################
[environments]
# The 'default' environment is activated with `pixi shell`.
# It contains all the tools needed to build the JupyterLite site.
default = { features = ["build"] }

# The 'kernel' environment is a minimal, isolated environment containing
# only the WASM-compiled kernel and its runtime dependencies.
kernel = { features = ["kernel"] }

# The 'ocaml' environment is for native OCaml development.
ocaml = { features = ["ocaml"] }

# The 'test' environment is for running the JavaScript tests.
test = { features = ["test"] }

# The 'docs' environment for building and serving documentation.
docs = { features = ["docs"] }

dev-tools = { features = ["dev-tools"] }

# The 'extension' environment provides the necessary tools (like Node.js)
# for developing the JupyterLab frontend extension.
extension = { features = ["extension"] }

###############################################################################
### [activation]: Activation Scripts and Variables
#
# Defines environment variables that will be set automatically when any pixi
# environment is activated.
###############################################################################
[activation.env]
# Sets a variable pointing to the OCaml source directory.
OCAML_DIR = "$PIXI_PROJECT_ROOT/ocaml"
# Sets the root directory for the OCaml Package Manager (OPAM).
OPAMROOT = "$PIXI_PROJECT_ROOT/.opam"