Skip to main content
Version: Current

Includes

An include lets one CRADLE file reuse definitions stored in another local CRADLE file.

The simplest way to think about it is:

Read the named file and add its CRADLE definitions to this scenario before validating or compiling it.

It is useful when multiple scenarios need the same router, network, object, or event. The shared definition can be maintained once instead of copied into every scenario.

include is supported by the current CradleXC parser.

A small example​

Suppose the scenario directory contains two files:

scenarios/
├── HelloWorld.cradle
└── shared/
    └── router.cradle

The shared file, shared/router.cradle, contains the router definition:

shared/router.cradle
instance("router") >
    os("linux", "20.04"),
    config("linux-router").

The main scenario includes that file:

HelloWorld.cradle
include "shared/router.cradle".

metadata() >
    name("HelloWorld"),
    eventType("sequence").

instances() >
    instance("router").

CradleXC processes this as though the router definition from shared/router.cradle were also part of HelloWorld.cradle:

metadata() >
    name("HelloWorld"),
    eventType("sequence").

instances() >
    instance("router").

instance("router") >
    os("linux", "20.04"),
    config("linux-router").

The included file is not downloaded and does not install anything. It is only a local source file that CradleXC reads and merges into the scenario.

Include syntax​

Use the singular keyword include, followed by a double-quoted path and a terminating period:

include "relative/path.cradle".

Each include is a separate statement:

include "shared/router.cradle".
include "shared/network.cradle".

How paths are resolved​

The path is relative to the file containing the include, not necessarily the directory where the terminal was opened.

In the earlier example, this statement in scenarios/HelloWorld.cradle:

include "shared/router.cradle".

resolves to scenarios/shared/router.cradle.

Included files can include other files. Each nested path is resolved relative to the file that contains it.

What can be shared​

An included file can contribute:

  • instance definitions
  • network definitions
  • object definitions
  • event definitions and lifecycle entries
  • object and heuristic declarations from metadata

Keep scenario-wide metadata such as name(), eventType(), repository settings, and credentials in the top-level file. This makes it clear which file owns the scenario configuration and avoids metadata merge ambiguity.

Names still have to match​

Including a file does not relax CRADLE's cross-reference rules. For example, this declaration in the main file:

instances() >
    instance("router").

must match the included definition exactly:

instance("router") >
    os("linux", "20.04").

The same rule applies to networks, objects, events, endpoint(), runObject(), and dependsOn() references.

Validation and errors​

Validate the top-level file, not each fragment individually:

cxc validate -i scenarios/HelloWorld.cradle

CradleXC resolves the includes first and then validates the combined scenario. It can therefore detect unresolved references and duplicate names across the participating files.

An include can fail when:

  • the path does not exist or cannot be read
  • the included file contains invalid CRADLE syntax
  • two files define the same instance, network, object, or event name
  • a reference does not match the name defined in another file
  • files include one another in a cycle

When to use an include​

Use includes when a definition is genuinely shared or when a large scenario is easier to maintain as several focused files. Keep a small scenario in one file when splitting it would make the scenario harder to follow.