Using the Slice Compiler

6 min read

3 min read

7 min read

5 min read

3 min read

4 min read

3 min read

3 min read

2 min read

Ice provides a Slice compiler for each language mapping. The compilers share a similar command-line syntax:

Shell
slice2<name> [options] file...

In MATLAB, you run the Slice-to-MATLAB compiler with the slice2matlab function of the Ice toolbox, as shown in Running the Compiler.

Regardless of which compiler you use, a number of command-line options are common to the compilers for any language mapping:

  • -h, --help Displays a help message.
  • -v, --version Displays the compiler version.
  • -DNAME Defines the preprocessor symbol NAME with the value 1.
  • -DNAME=DEF Defines the preprocessor symbol NAME with the value DEF.
  • -UNAME Undefines the preprocessor symbol NAME.
  • -IDIR Add the directory DIR to the search path for #include directives.
  • --output-dir DIR Place the generated files into directory DIR, which must already exist.
  • -d, --debug Print debug information showing the operation of the Slice parser.

The following options print dependency information:

  • --depend Print dependency information in Makefile format to standard output by default, or to the file specified by the --depend-file option.
  • --depend-xml Print dependency information in XML format to standard output by default, or to the file specified by the --depend-file option.
  • --depend-file FILE Directs dependency information to the specified file. The output format depends on whether --depend or --depend-xml is specified.
  • --depend-xml Print dependency information in XML format to standard output by default, or to the file specified by the --depend-file option.
  • --depend-file FILE Directs dependency information to the specified file.
  • --depend Print dependency information in Makefile format to standard output by default, or to the file specified by the --depend-file option.
  • --depend-xml Print dependency information in XML format to standard output by default, or to the file specified by the --depend-file option.
  • --depend-json Print dependency information in JSON format to standard output by default, or to the file specified by the --depend-file option.
  • --depend-file FILE Directs dependency information to the specified file. The output format depends on whether --depend, --depend-xml, or --depend-json is specified.

With these options, the compiler prints the complete list of Slice files that the input Slice files depend on, through direct or indirect inclusion, and generates no code.

The Slice compilers permit you to compile more than a single source file, so you can compile several Slice definitions at once, for example:

Shell
slice2cpp -I. file1.ice file2.ice file3.ice

Each compiler predefines macros that identify the compiler and the Ice version; see Conditional Compilation.

The Slice-to-C++ compiler (slice2cpp) offers the following additional options:

Changes the file extension for the generated header files from the default h to the extension specified by EXT.

The cpp:header-ext file directive sets the header extension of one Slice file and takes precedence over this option. When another Slice file includes this file, the generated #include directive uses the same extension. For example, Ice/BuiltinSequences.ice contains [["cpp:header-ext:h"]], so compiling

Slice
// example.ice
#include <Ice/BuiltinSequences.ice>

with slice2cpp --header-ext=hpp -I/opt/Ice/slice example.ice generates example.hpp, which includes Ice/BuiltinSequences.h.

Changes the file extension for the generated source files from the default cpp to the extension specified by EXT.

This option adds an include directive for the specified header at the beginning of the generated source file (preceding any other include directives). If GUARD is specified, the include directive is protected by the specified guard. For example, --add-header precompiled.h,__PRECOMPILED_H__ results in the following directives at the beginning of the generated source file:

C++
#ifndef __PRECOMPILED_H__
#define __PRECOMPILED_H__
#include <precompiled.h>
#endif

The option can be repeated to create include directives for several files.

As suggested by the preceding example, this option is useful mainly to integrate the generated code with a compiler's precompiled header mechanism.

Prepends the directory DIR to the path in the #include directive that the generated source file uses to include its own header file.

The -I and --include-dir options determine the paths of the #include directives that slice2cpp generates. The --output-dir option determines where the compiler writes the generated files, but does not change their content.

The header generated from a Slice file includes the header generated from each Slice file it includes. The compiler builds the path of this #include directive from the path of the included Slice file: when it finds the included file in an -I directory, it removes the -I directory from the path, and when several -I directories contain the file, it uses the one that gives the shortest path. For example, suppose slice/inc/A.ice contains:

Slice
// A.ice
#include <slice/inc/B.ice>
Command#include directive in A.h
slice2cpp -I. slice/inc/A.ice
#include <slice/inc/B.h>
slice2cpp -I. -Islice slice/inc/A.ice
#include <inc/B.h>
slice2cpp -I. -Islice -Islice/inc slice/inc/A.ice
#include <B.h>

The -I option therefore plays two roles: it lets the compiler locate included Slice files, and it shortens the generated #include directives. In the last two commands, -I. locates slice/inc/B.ice, and the other -I options only shorten the generated directive.

With a Slice #include directive in double quotes, the compiler first looks for the file relative to the including file. When it finds the file there, the generated directive keeps the path of the Slice directive, in double quotes, whatever the -I options: if slice/inc/A.ice contains #include "B.ice", A.h contains #include "B.h".

The generated source file includes its own header by the base name of the header: compiling inc/A.ice generates #include "A.h" in A.cpp. The --include-dir option adds a directory to this path: with slice2cpp --include-dir src -I. inc/A.ice, A.cpp contains #include "src/A.h". The directory of the Slice file, inc, does not appear in either generated #include directive.

Ice for C++ ships with a CMake package that defines an imported target for each Ice library and provides the slice2cpp_generate function, which compiles the Slice files of a target as part of the build. See Using Ice with CMake.

The Slice-to-C# compiler (slice2cs) supports the following additional options:

  • --icerpc Generates code for IceRPC instead of Ice, in a file named <base name>.IceRpc.cs. See Using Ice and IceRPC Together.
  • --enable-analysis Omits the <auto-generated> comment from the generated files, which enables .NET code analysis of the generated code.

The Slice-to-Java compiler (slice2java) offers one additional option:

  • --list-generated Emit a list of generated files in XML format.

The com.zeroc.slice-tools Gradle plugin compiles the Slice files of a Java or Android project with slice2java and adds the generated Java files to the project's sources. Apply it after the Java or Android plugin:

Kotlin
plugins {
java
id("com.zeroc.slice-tools") version "3.8.+"
}

The plugin includes slice2java for Linux (x64 and arm64), macOS (arm64), and Windows (x64), as well as the Slice files of Ice, Glacier2, IceBox, IceGrid, IceStorm, and DataStorm. By default, it compiles your Slice files with the included slice2java and puts the included Slice files on the include path, so your Slice files can #include <Ice/Identity.ice>.

The slice block of the project holds the Slice source sets and the settings that apply to all of them:

SettingDescription
compilerArgs
Arguments the plugin passes to slice2java, such as -D options.
includeSearchPath
Directories the plugin passes to slice2java with -I.
sourceSets
The Slice source sets of the project, one for each Java or Android source set.
toolsPath
The directory that holds the slice2java to run instead of the included one, for example from a local Ice build or on a platform the plugin doesn't include. With toolsPath set, the included Slice files are not on the include path; add their directory to includeSearchPath when your Slice files include them.
Kotlin
slice {
includeSearchPath.from("../common/slice")
compilerArgs.addAll("-DUSE_TRACING")
}

The plugin adds a Slice source set to each Java source set, such as main and test, and to each Android source set, such as main, debug, and release. A Slice source set compiles the .ice files under src/<source set>/slice by default, and holds settings of its own:

SettingDescription
srcDir, srcDirs
Add directories of Slice files to the source set. setSrcDirs replaces the directories, including the default one.
includeSearchPath
Directories the plugin passes to slice2java with -I for this source set.
compilerArgs
Arguments the plugin passes to slice2java for this source set.

For each source set, the plugin passes the include search path and the compiler arguments of the project, followed by those of the source set. You configure a Slice source set in the slice block of its Java or Android source set:

Kotlin
sourceSets {
main {
slice {
srcDirs("../slice")
includeSearchPath.from("../common/slice")
}
}
}

The plugin registers a compileSlice<SourceSet> task for each source set, such as compileSliceMain, that generates Java files into build/generated/source/slice/<source set> in a Java project, and into build/generated/java/compileSlice<SourceSet> in an Android project. The compileSlice task runs all of them.

The plugin compiles incrementally: it recompiles a Slice file when the file or a file it includes changes, deletes the Java files that a Slice file no longer generates, and recompiles every Slice file when the compiler arguments change.

In a Java project, the plugin adds the Java files generated from each Slice source set to the Java sources of the same source set: the Java compiler compiles the files generated from src/test/slice with the test classes.

In an Android project, the plugin adds the generated Java files to the Java sources of each build variant, from the Slice source sets that contribute to the variant: main, the build type, each product flavor, the combination of the product flavors, and the combination of the product flavors and the build type. For example, the freeDebug variant of a project with a free product flavor compiles the files generated from src/main/slice, src/debug/slice, src/free/slice, and src/freeDebug/slice.

In a Groovy build script, you configure a Slice source set in the slice block of its Android source set:

Groovy
android {
sourceSets {
main {
slice {
srcDir "../slice"
}
}
}
}

In a Kotlin build script, Gradle generates the slice accessor only for Java source sets, so you configure the Slice source set of an Android source set through its extensions:

Kotlin
android {
sourceSets {
getByName("main") {
(this as ExtensionAware).extensions.configure<com.zeroc.slice.tools.SliceSourceSet>("slice") {
srcDir("../slice")
}
}
}
}

The Slice-to-JavaScript compiler (slice2js) offers the following command-line options in addition to the standard options:

  • --stdout Print generated code to standard output.
  • --typescript Generate a TypeScript declaration file (.d.ts) next to each generated JavaScript file.

The @zeroc/ice package includes the slice2js compiler for Linux (x64 and arm64), macOS (arm64), and Windows (x64). Run it with npx:

Shell
npx slice2js --output-dir src/generated slice/Greeter.ice

The slice2js command adds the Slice files of Ice, which the package includes, to the include search path, so your Slice files can include them, as in #include <Ice/Identity.ice>.

The optional @zeroc/slice2js package provides a plug-in that compiles your Slice files at the start of each build of a Vite, Rollup, webpack, or esbuild project. Install it as a development dependency:

Shell
npm install --save-dev @zeroc/slice2js

Import the plug-in for your bundler from its entry point:

BundlerEntry point
Vite
@zeroc/slice2js/unplugin/vite
Rollup
@zeroc/slice2js/unplugin/rollup
webpack
@zeroc/slice2js/unplugin/webpack
esbuild
@zeroc/slice2js/unplugin/esbuild

Then add the plug-in to the configuration of your bundler. For example, with Vite:

vite.config.js
import slice2js from "@zeroc/slice2js/unplugin/vite";
export default {
plugins: [
slice2js({
inputs: ["slice/*.ice"],
outputDir: "src/generated",
include: ["slice"],
args: ["--typescript"],
}),
],
};

The plug-in accepts the following options:

OptionDescription
inputs
The Slice files to compile, as file names or glob patterns. Required.
outputDir
The directory for the generated files. The plug-in creates it if it doesn't exist. Required.
include
Additional directories for the include search path of slice2js.
args
Additional slice2js command-line options, such as --typescript.
cwd
The directory against which the relative paths in inputs, outputDir, and include resolve. Defaults to the current directory.
toolsPath
The directory of a slice2js executable that replaces the one in the package.
slicePath
The directory of Slice files that replaces the Slice files of Ice in the include search path.

To compile Slice files from your own build script, call runSlice2js from @zeroc/slice2js/unplugin, which takes the same options as the plug-in, or compile from @zeroc/slice2js, which takes the slice2js command-line arguments and returns the exit code of the compiler:

JavaScript
import { runSlice2js } from "@zeroc/slice2js/unplugin";
await runSlice2js({ inputs: ["slice/*.ice"], outputDir: "src/generated", args: ["--typescript"] });

The Slice-to-MATLAB compiler offers two additional options:

  • --all Generate code for all Slice definitions, including those from included files.
  • --list-generated Emit a list of generated files in XML format.

slice2matlab does not support the --depend flag, although it does still support --depend-xml and --depend-file.

The Ice toolbox provides the Slice-to-MATLAB compiler and a slice2matlab function that runs it. You call this function from the MATLAB console or from a MATLAB script. It adds the directory of the Ice Slice files to the include search path, forwards its arguments to the compiler, and returns the compiler's exit status:

MATLAB
slice2matlab Greeter.ice
status = slice2matlab('--output-dir', 'generated', 'Greeter.ice');

The Slice-to-PHP compiler (slice2php) offers one additional option:

  • --all Generate code for all Slice definitions, including those from included files.

For each Slice file X.ice, slice2php generates PHP code into a file named X.php in the output directory. The default output directory is the current working directory, but a different directory can be specified using the --output-dir option.

Without the --all option, the compiler generates no code for Slice definitions in included files. Instead, it translates each #include directive into a require_once statement for the PHP file generated from the included file, and places these statements in a global namespace block.

Each require_once statement uses the shortest of these paths: the path from the #include directive, and the path of the included file relative to each include directory (specified with -I) that contains it. For example, if /opt/App/slice/Main.ice contains #include <Process.ice> and you specify -I/opt/App/slice/OS and -I/opt/App/slice, the compiler generates:

PHP
namespace
{
require_once 'Process.php';
}

If Main.ice contains #include "OS/Process.ice" instead, the compiler generates require_once 'OS/Process.php'; even with -I/opt/App, because OS/Process is shorter than slice/OS/Process.

The Slice-to-Python compiler (slice2py) supports the following additional options:

  • --build=modules|index|all Selects which Python files the compiler generates.
  • --list-generated=modules|index|all Prints the paths of the Python files that the compiler would generate, relative to the output directory and one per line, without generating them.

The value selects the files:

ValueFiles
modules
The Python module files for the Slice definitions.
index
The Python package index files (__init__.py).
all
Both module and index files. What the compiler generates without --build.

The Slice-to-Ruby compiler (slice2rb) offers one additional option:

  • --all Generate code for all Slice definitions, including those from included files.

The Slice-to-Swift compiler (slice2swift) supports only the common Slice compiler options.