Skip to content

xtc-cli.md

Latest commit

 

History

History
327 lines (248 loc) · 7.36 KB

xtc-cli.md

File metadata and controls

327 lines (248 loc) · 7.36 KB

XTC Command-Line Interface

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:

  1. File → New → Project
  2. Select XTC from the generators list
  3. 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.