The xtc command is the unified command-line tool for working with Ecstasy projects.
| 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 bundle |
Merge compiled modules into a single multi-module .xtc file |
Creates a new XTC project with the standard directory structure and build files.
xtc init <project-name> [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 |
# 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-moduleAn 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 # ExecuteA 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 executableSimilar 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 # ExecuteThe --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 libCompiles Ecstasy source files into .xtc module files.
xtc build [options] <source_files>| 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 |
xtc build src/main/x/myapp.x
xtc build -L lib/ -o build/ src/main/x/myapp.x
xtc build --rebuild myapp.xExecutes a compiled Ecstasy module.
xtc run [options] <module> [args...]| 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 |
xtc run myapp.xtc
xtc run -L lib/ myapp.xtc
xtc run -M main myapp.xtc
xtc run -I config=prod myapp.xtc arg1 arg2Runs tests in an Ecstasy module using the xunit framework.
xtc test [options] <module>| 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 |
xtc test myapp.xtc
xtc test -c MyTests myapp.xtc
xtc test --test-group integration myapp.xtcDisassembles a compiled .xtc module to inspect its contents.
xtc disass [options] <module_file>| Option | Description |
|---|---|
--files |
List embedded files in the module |
--findfile <file> |
Search for a specific file |
xtc disass myapp.xtc
xtc disass --files myapp.xtc
xtc disass --findfile config.json myapp.xtcMerges compiled modules into a single multi-module .xtc file (a "bundle"). The result is a
self-contained module repository: both the runner and the compiler can resolve every bundled
module from it by name, so one file can replace a lib/ directory full of .xtc files.
Multi-module bundle output is tagged as FileTemplate.Kind.Library in the .xtc header, with the
real module names recorded separately from dependency fingerprints. Single-module output remains
Single.
With no explicit module selection, every non-system module found on the module path is bundled.
System (xtclang.org) modules are never bundled implicitly; they remain external dependencies,
resolved from the XDK at run time, exactly as with a lib directory. Pass --include-system to
lift that exclusion when building a fully self-contained artifact (this is how
./gradlew xdk:bundleXdk produces the single-file XDK, xdk.xtc).
For the concepts, internal mechanics, and limitations, see XTC Bundles.
xtc bundle [options] [<module_name_or_file> ...]| Option | Description |
|---|---|
-L <path> |
Module path to select modules from and resolve dependencies against |
-o, --output <file> |
File (or directory) to write the bundle to; defaults to <main>.bundle.xtc |
--main <module> |
Qualified name of the module to use as the bundle's main module; defaults to the only selected module that no other selected module imports |
--include-system |
Also bundle system (xtclang.org) modules when selecting from the module path (used to build a fully self-contained single-file XDK) |
Like the other verbs, bundle is quiet on success; add -v to see the bundled module list, the
remaining external (run-time-resolved) dependencies, and warnings about modules that are present
on the module path but not included in the bundle.
# Bundle all application modules from a lib directory (main module inferred)
xtc bundle -L build/install/myapp/lib
# Bundle with an explicit main module and output file
xtc bundle -L lib --main kernel.xqiz.it -o myapp.xtc
# Run an application directly from its bundle
xec -L ./myapp.xtc ./myapp.xtc
# Build the single-file XDK, then use it as the entire system library:
# compile, run, or even boot a fully bundled deployment with no lib directories at all
./gradlew xdk:bundleXdk
java -jar javatools.jar build -L xdk.xtc MyApp.x
java -jar javatools.jar run -L xdk.xtc -L myapp.xtc myapp.xtcThe 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.