Includes

A .oce file can include other .oce files. This lets you compose larger pipelines from smaller, reusable pieces without putting everything in one file.

Basic include

Add an include list to [config]:

[config]
include = ["./prepare.oce", "./analyse.oce", "./report.oce"]

When this file is run, the three included files execute in order before the tasks defined in the current file. Each file must complete before the next begins.

Parallel includes

Wrap filenames in an inner array to run them concurrently:

[config]
include = [
  "./prepare.oce",
  ["./analyse-group-a.oce", "./analyse-group-b.oce"],
  "./report.oce"
]

This runs:

1. prepare.oce — completes first
2. analyse-group-a.oce and analyse-group-b.oce — run at the same time
3. report.oce — starts only after both analysis files have finished

Parallel includes are useful when you have independent workloads that can run simultaneously. The next stage always waits for all files in a parallel group to complete.

Error handling across includes

By default, a failure in one included file does not stop the remaining files. To propagate the stop-on-error behaviour:

[config]
stop_on_error = true
include = ["./step1.oce", "./step2.oce"]

With stop_on_error = true, if step1.oce fails, step2.oce is skipped and tasks in the current file are also skipped.

Paths

Include paths are relative to the file that declares them, not to the working directory where you launched the run. This means you can organise files in subdirectories and move the whole folder without breaking includes:

project/
├── run.oce            [config] include = ["./steps/prepare.oce", ...]
└── steps/
    ├── prepare.oce
    ├── analyse.oce
    └── report.oce

Absolute paths also work but make files less portable.

Nesting

Included files can themselves include other files. There is no enforced depth limit, but deeply nested include trees are harder to follow. A flat or two-level structure covers most workflows.

When to use includes

Includes are most useful when:

• You have a pipeline with discrete stages that are meaningful on their own
• Some stages can run in parallel, saving wall-clock time
• You want to share a preparation or cleanup step across several top-level files
• A single file is getting long enough to be hard to navigate

For simple one-shot calculations or quick experiments, a single .oce file with multiple tasks is simpler and more readable.