XTC Command-Line Interface

February 4, 2026 · View on GitHub

The xtc command is the unified command-line tool for working with Ecstasy projects.

Commands

Command	Description
`xtc init`	Create a new XTC project
`xtc build`	Compile Ecstasy source files (alias: `xcc`)
`xtc run`	Execute an Ecstasy module (alias: `xec`)
`xtc test`	Run tests in an Ecstasy module using xunit
`xtc disass`	Disassemble a compiled Ecstasy module

xtc init - Project Creation

Creates a new XTC project with the standard directory structure and build files.

Usage

xtc init <project-name> [options]

Options

Option	Description
`-t, --type <type>`	Project type: `application` (default), `library`, or `service`
`-m, --multi-module`	Create a multi-module project structure
`-v, --verbose`	Enable verbose output
`-h, --help`	Display help message

Examples

# Create an application project (default)
xtc init myapp

# Create a library project
xtc init mylib --type=library
xtc init mylib -t lib

# Create a service project
xtc init mysvc --type=service

# Create a multi-module project
xtc init myproject --multi-module
xtc init myproject -m

# Combine options
xtc init myproject --type=service --multi-module

Project Types

APPLICATION

An executable module with an entry point. This is the default project type.

Use when: You want to create a runnable program.

Generated structure:

myapp/
├── build.gradle.kts      # Includes xtcRun configuration
├── settings.gradle.kts
├── gradle.properties
├── gradle/
│   └── libs.versions.toml
├── gradlew / gradlew.bat
└── src/main/x/
    └── myapp.x           # Module with void run() entry point

Generated module source:

module myapp {
    void run() {
        @Inject Console console;
        console.print("Hello from myapp!");
    }
}

Build commands:

./gradlew build    # Compile
./gradlew run      # Execute

LIBRARY

A reusable module that exports types and services for other modules to import. Has no entry point.

Use when: You want to create shared functionality that other projects will depend on.

Generated structure:

mylib/
├── build.gradle.kts      # No xtcRun configuration
├── settings.gradle.kts
├── gradle.properties
├── gradle/
│   └── libs.versions.toml
├── gradlew / gradlew.bat
└── src/main/x/
    └── mylib.x           # Module with exported service

Generated module source:

module mylib {
    /**
     * A greeting service.
     */
    service Greeter {
        String greet(String name) {
            return $"Hello, {name}!";
        }
    }
}

Build commands:

./gradlew build    # Compile (produces .xtc file)
# No 'run' task - libraries are not executable

SERVICE

Similar to APPLICATION but semantically intended for background/daemon processes.

Use when: You want to create a long-running service or daemon.

Generated structure: Same as APPLICATION.

Generated module source:

module mysvc {
    void run() {
        @Inject Console console;
        console.print("mysvc service starting...");

        // TODO: Add your service logic here
    }
}

Build commands:

./gradlew build    # Compile
./gradlew run      # Execute

Multi-Module Projects

The --multi-module flag creates a project with multiple subprojects that can depend on each other.

Generated structure:

myproject/
├── settings.gradle.kts   # Includes app and lib subprojects
├── gradle.properties
├── gradle/
│   └── libs.versions.toml
├── gradlew / gradlew.bat
├── app/
│   ├── build.gradle.kts
│   └── src/main/x/
│       └── app.x         # Application that imports lib
└── lib/
    ├── build.gradle.kts
    └── src/main/x/
        └── lib.x         # Library module

Note: Multi-module projects do not have a root build.gradle.kts. Each subproject is self-contained with its own build file, and settings.gradle.kts defines the project structure. This is the recommended modern Gradle style.

app.x imports lib:

module app {
    package lib import lib;

    void run() {
        @Inject Console console;

        // Use the Greeter service from lib
        lib.Greeter greeter = new lib.Greeter();
        console.print(greeter.greet("World"));
    }
}

Build commands:

./gradlew build    # Build all subprojects
./gradlew run      # Run the app module
./gradlew :app:build   # Build only app
./gradlew :lib:build   # Build only lib

xtc build - Compilation

Compiles Ecstasy source files into .xtc module files.

Usage

xtc build [options] <source_files>

Options

Option	Description
`-L <path>`	Module path for dependencies
`-o <file>`	Output file or directory
`-r <path>`	Resource path
`--rebuild`	Force rebuild
`--strict`	Treat warnings as errors
`--nowarn`	Suppress warnings
`-v, --verbose`	Verbose output

Examples

xtc build src/main/x/myapp.x
xtc build -L lib/ -o build/ src/main/x/myapp.x
xtc build --rebuild myapp.x

xtc run - Execution

Executes a compiled Ecstasy module.

Usage

xtc run [options] <module> [args...]

Options

Option	Description
`-L <path>`	Module path
`-M <method>`	Entry method name (default: `run`)
`-I <name=value>`	Injection values
`-J, --jit`	Enable JIT compiler
`--no-recompile`	Disable automatic recompilation

Examples

xtc run myapp.xtc
xtc run -L lib/ myapp.xtc
xtc run -M main myapp.xtc
xtc run -I config=prod myapp.xtc arg1 arg2

xtc test - Testing

Runs tests in an Ecstasy module using the xunit framework.

Usage

xtc test [options] <module>

Options

Option	Description
`-c, --test-class <class>`	Run tests in specific class
`-g, --test-group <group>`	Run tests with specific @Test group
`-p, --test-package <pkg>`	Run tests in specific package
`-t, --test-method <method>`	Run specific test method
`--xunit-out <dir>`	Output directory for test results

Examples

xtc test myapp.xtc
xtc test -c MyTests myapp.xtc
xtc test --test-group integration myapp.xtc

xtc disass - Disassembly

Disassembles a compiled .xtc module to inspect its contents.

Usage

xtc disass [options] <module_file>

Options

Option	Description
`--files`	List embedded files in the module
`--findfile <file>`	Search for a specific file

Examples

xtc disass myapp.xtc
xtc disass --files myapp.xtc
xtc disass --findfile config.json myapp.xtc

IntelliJ IDEA Integration

The XTC IntelliJ plugin provides a New Project wizard that offers the same project types and options as xtc init:

File → New → Project
Select XTC from the generators list
Configure:
- Project name and Location
- Project type: Application, Library, or Service
- Multi-module project checkbox

The wizard uses the same XtcProjectCreator as xtc init, ensuring identical project structures whether created from the command line or IDE.