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
Common Options
Ice provides a Slice compiler for each language mapping. The compilers share a similar command-line syntax:
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, --helpDisplays a help message.-v, --versionDisplays the compiler version.-DNAMEDefines the preprocessor symbolNAMEwith the value1.-DNAME=DEFDefines the preprocessor symbolNAMEwith the valueDEF.-UNAMEUndefines the preprocessor symbolNAME.-IDIRAdd the directoryDIRto the search path for#includedirectives.--output-dirDIRPlace the generated files into directoryDIR, which must already exist.-d, --debugPrint debug information showing the operation of the Slice parser.
The following options print dependency information:
--dependPrint dependency information in Makefile format to standard output by default, or to the file specified by the--depend-fileoption.--depend-xmlPrint dependency information in XML format to standard output by default, or to the file specified by the--depend-fileoption.--depend-file FILEDirects dependency information to the specified file. The output format depends on whether--dependor--depend-xmlis specified.
--depend-xmlPrint dependency information in XML format to standard output by default, or to the file specified by the--depend-fileoption.--depend-file FILEDirects dependency information to the specified file.
--dependPrint dependency information in Makefile format to standard output by default, or to the file specified by the--depend-fileoption.--depend-xmlPrint dependency information in XML format to standard output by default, or to the file specified by the--depend-fileoption.--depend-jsonPrint dependency information in JSON format to standard output by default, or to the file specified by the--depend-fileoption.--depend-file FILEDirects dependency information to the specified file. The output format depends on whether--depend,--depend-xml, or--depend-jsonis 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:
slice2cpp -I. file1.ice file2.ice file3.iceEach compiler predefines macros that identify the compiler and the Ice version; see Conditional Compilation.
The Slice Compiler for C++
The Slice-to-C++ compiler (slice2cpp) offers the following additional options:
--header-ext EXT
--header-ext EXTChanges 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
// 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.
--source-ext EXT
--source-ext EXTChanges the file extension for the generated source files from the default cpp to the extension specified by EXT.
--add-header HDR[,GUARD]
--add-header HDR[,GUARD]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:
#ifndef __PRECOMPILED_H__#define __PRECOMPILED_H__#include <precompiled.h>#endifThe 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.
--include-dir DIR
--include-dir DIRPrepends the directory DIR to the path in the #include directive that the generated source file uses to include its own header file.
Include Directives
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.
Header Files
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:
// 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".
Source Files
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.
Using Ice with CMake
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 Compiler for C#
The Slice-to-C# compiler (slice2cs) supports the following additional options:
--icerpcGenerates code for IceRPC instead of Ice, in a file named<base name>.IceRpc.cs. See Using Ice and IceRPC Together.--enable-analysisOmits the<auto-generated>comment from the generated files, which enables .NET code analysis of the generated code.
The Slice Compiler for Java
The Slice-to-Java compiler (slice2java) offers one additional option:
--list-generatedEmit a list of generated files in XML format.
Compiling Slice Files with Gradle
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:
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>.
Project Settings
The slice block of the project holds the Slice source sets and the settings that apply to all of them:
| Setting | Description |
|---|---|
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. |
slice { includeSearchPath.from("../common/slice") compilerArgs.addAll("-DUSE_TRACING")}Slice Source Sets
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:
| Setting | Description |
|---|---|
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:
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.
Java Projects
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.
Android Projects
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:
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:
android { sourceSets { getByName("main") { (this as ExtensionAware).extensions.configure<com.zeroc.slice.tools.SliceSourceSet>("slice") { srcDir("../slice") } } }}The Slice Compiler for JavaScript
The Slice-to-JavaScript compiler (slice2js) offers the following command-line options in addition to the standard options:
--stdoutPrint generated code to standard output.--typescriptGenerate a TypeScript declaration file (.d.ts) next to each generated JavaScript file.
Running slice2js
The @zeroc/ice package includes the slice2js compiler for Linux (x64 and arm64), macOS (arm64), and Windows (x64). Run it with npx:
npx slice2js --output-dir src/generated slice/Greeter.iceThe 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>.
Compiling Slice Files During the Build
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:
npm install --save-dev @zeroc/slice2jsImport the plug-in for your bundler from its entry point:
| Bundler | Entry 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:
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:
| Option | Description |
|---|---|
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:
import { runSlice2js } from "@zeroc/slice2js/unplugin";
await runSlice2js({ inputs: ["slice/*.ice"], outputDir: "src/generated", args: ["--typescript"] });The Slice Compiler for MATLAB
The Slice-to-MATLAB compiler offers two additional options:
--allGenerate code for all Slice definitions, including those from included files.--list-generatedEmit 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.
Running the Compiler
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:
slice2matlab Greeter.icestatus = slice2matlab('--output-dir', 'generated', 'Greeter.ice');The Slice Compiler for PHP
The Slice-to-PHP compiler (slice2php) offers one additional option:
--allGenerate code for all Slice definitions, including those from included files.
Compiler Output
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.
Include Files
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:
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 Compiler for Python
The Slice-to-Python compiler (slice2py) supports the following additional options:
--build=modules|index|allSelects which Python files the compiler generates.--list-generated=modules|index|allPrints 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:
| Value | Files |
|---|---|
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 Compiler for Ruby
The Slice-to-Ruby compiler (slice2rb) offers one additional option:
--allGenerate code for all Slice definitions, including those from included files.
The Slice Compiler for Swift
The Slice-to-Swift compiler (slice2swift) supports only the common Slice compiler options.