---
title: "Using the Slice Compiler"
url: https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Using the Slice Compiler

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/php.md), [Python](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/ruby.md), and [Swift](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/swift.md).

## Common Options

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

```shell
slice2<name> [options] file...
```

> **MATLAB**
>
> In MATLAB, you run the Slice-to-MATLAB compiler with the `slice2matlab` function of the Ice toolbox, as shown in [Running the Compiler](https://docs.zeroc.com/ice/3.8/slice/using-the-slice-compiler/matlab.md#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:

> **C++, C#, PHP, Python, Ruby, and Swift**
>
> - `--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.

> **Java and MATLAB**
>
> - `--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.

> **JavaScript**
>
> - `--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](https://docs.zeroc.com/ice/3.8/slice/slice-source-files.md#conditional-compilation).

> **C++**
>
> ## The Slice Compiler for C++
>
> The Slice-to-C++ compiler (`slice2cpp`) offers the following additional options:
>
> ### `--header-ext` `EXT`
>
> 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`.
>
> ### `--source-ext` `EXT`
>
> Changes the file extension for the generated source files from the default `cpp` to the extension specified by `EXT`.
>
> ### `--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:
>
> ```cpp
> #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.
>
> ### `--include-dir DIR`
>
> Prepends 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:
>
> ```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"`.
>
> ### 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](https://docs.zeroc.com/ice/3.8/build-tools/cmake.md).

> **C#**
>
> ## The Slice Compiler for C#
>
> 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](https://docs.zeroc.com/ice/3.8/icerpc.md#using-ice-files-with-icerpc).
> - `--enable-analysis` Omits the `<auto-generated>` comment from the generated files, which enables .NET code analysis of the generated code.

> **Java**
>
> ## The Slice Compiler for Java
>
> The Slice-to-Java compiler (`slice2java`) offers one additional option:
>
> - `--list-generated` Emit 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:
>
> ```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>`.
>
> ### 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. |
>
> ```kotlin
> 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:
>
> ```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.
>
> ### 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:
>
> ```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")
>             }
>         }
>     }
> }
> ```

> **JavaScript**
>
> ## The Slice Compiler for JavaScript
>
> 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.
>
> ## Running slice2js
>
> 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>`.
>
> ## 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:
>
> ```shell
> npm install --save-dev @zeroc/slice2js
> ```
>
> Import 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:
>
> ```js title="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:
>
> | 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:
>
> ```js
> import { runSlice2js } from "@zeroc/slice2js/unplugin";
>
> await runSlice2js({ inputs: ["slice/*.ice"], outputDir: "src/generated", args: ["--typescript"] });
> ```

> **MATLAB**
>
> ## The Slice Compiler for MATLAB
>
> 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`.
>
> ### 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:
>
> ```matlab
> slice2matlab Greeter.ice
> status = slice2matlab('--output-dir', 'generated', 'Greeter.ice');
> ```

> **PHP**
>
> ## The Slice Compiler for PHP
>
> The Slice-to-PHP compiler (`slice2php`) offers one additional option:
>
> - `--all` Generate 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:
>
> ```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`.

> **Python**
>
> ## The Slice Compiler for Python
>
> 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:
>
> | 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`. |

> **Ruby**
>
> ## The Slice Compiler for Ruby
>
> The Slice-to-Ruby compiler (`slice2rb`) offers one additional option:
>
> - `--all` Generate code for all Slice definitions, including those from included files.

> **Swift**
>
> ## The Slice Compiler for Swift
>
> The Slice-to-Swift compiler (`slice2swift`) supports only the common Slice compiler options.

## See Also

- [Slice Compilation](https://docs.zeroc.com/ice/3.8/slice/slice-compilation.md)
