Skip to content

Latest commit

 

History

History
146 lines (105 loc) · 7.5 KB

README.md

File metadata and controls

146 lines (105 loc) · 7.5 KB
Raw

Slice Tools for IceRPC

IceRpc.Slice.Tools allows you to compile Slice definitions (in .slice files) into C# code (in .cs files) within MSBuild projects.

This package includes the Slice compiler for C#, slicec-cs. This compiler is a native tool with binaries for Linux (x64 and arm64), macOS (x64 and arm64) and Windows (x64).

Once you've added the IceRpc.Slice.Tools NuGet package to your project, the Slice files of your project are automatically compiled into C# files every time you build this project.

When slicec-cs compiles a Slice file and the resulting .cs file is identical to the existing output .cs file, the existing .cs file is kept as-is; the output file is overwritten only when something changed.

Source code | Package | slicec-cs options | Slice documentation

Slice files and Slice directories

The Slice compiler for C# accepts two main inputs:

  • the Slice files to compile into C# code (the Slice files)
  • directories that contain reference Slice files (the Slice directories)

The Slice compiler parses the reference Slice files found in the Slice directories but does not generate code for them. They typically contain definitions referenced by the source Slice files.

The Slice files and Slice directories can overlap.

You select which files to include in your project's Slice files with the SliceFile item type. And you select which directory to include in your project's Slice directories with the SliceDirectory item type.

By default, all .slice files located in your project's home directory and any of its subdirectories, recursively, are included in SliceFile. You can prevent this auto-inclusion of .slice files by setting either EnableDefaultItems or EnableDefaultSliceFileItems to false. The default value of these properties is true.

You can also add Slice files to your project explicitly. For example:

<ItemGroup>
    <SliceFile Include="../Greeter.slice"/>
</ItemGroup>

This adds Greeter.slice to your project's Slice files even though this file is not in the project's home directory or any of its subdirectories.

Slice files must have a .slice extension.

The Slice directories are an aggregate of the SliceDirectory defined in your project (if any) and the SliceDirectory defined in NuGet packages referenced by your project.

For example, if your project's Slice files reference definitions in directory common/slice:

<ItemGroup>
    <SliceDirectory Include="$(MSBuildThisFileDirectory)../common/slice"/>
</ItemGroup>

Slice directory and NuGet package

As a general rule, when you package an assembly in a NuGet package and this assembly exports C# symbols generated by the Slice compiler for C#, you should include the corresponding Slice files in your NuGet package. This allows consumers of your NuGet package to easily retrieve these Slice files.

You can also define SliceDirectory in this NuGet package so that any project that references this package automatically sees these Slice files when compiling.

For example, if you pack Slice files into the slice directory of your NuGet package, you want to include the following ItemGroup in the buildTransitive/<PackageName>.props you pack into this package:

<ItemGroup>
    <SliceDirectory Include="$(MSBuildThisFileDirectory)../slice"/>
</ItemGroup>

The ZeroC.Slice NuGet package follows this pattern and provides definitions for common Slice types such as WellKnownTypes::Duration, WellKnownTypes::TimeStamp and WellKnownTypes::Uri.

SliceFile item metadata

You can use the following SliceFile item metadata to customize the compilation and packaging of your Slice files. Each unique set of options results in a separate execution of slicec-cs.

Name Default Description
AdditionalOptions Specifies additional options to pass to slicec-cs.
OutputDir generated Sets the output directory for the generated code. This metadata corresponds to the --output-dir option of slicec-cs.
Pack false Specifies whether or not to include the items (Slice files) in the NuGet package.
PackagePath slice Sets the target path in the NuGet package. Used only when Pack is true.
Rpc icerpc Specifies the RPC framework to generate code for. Possible values: icerpc, none. This metadata corresponds to the --rpc option of slicec-cs

Generated code and NuGet packages

You need to reference the following NuGet packages to compile the generated C# code:

Rpc metadata NuGet package reference
icerpc or no Rpc metadata IceRpc.Slice
none ZeroC.Slice

Referencing IceRpc.Slice makes your project reference transitively ZeroC.Slice, IceRpc and System.IO.Pipelines.

Build telemetry

The IceRpc.Slice.Tools package collects anonymous build telemetry data about general usage. Participation in this program is optional, and you may opt out if you’d prefer not to share any information.

This package includes the IceRpc.SliceBuildTelemetry.Reporter client, an IceRPC C# client that sends anonymous build telemetry data over a secure connection to the IceRPC build telemetry server during the compilation of Slice files. This data includes:

  • The IceRPC version.
  • The system's operating system, version, and platform architecture.
  • The source of the telemetry data (IceRpc.Slice.Tools).
  • The number of Slice files being compiled.
  • The number of Slice reference files.
  • Whether or not the build contains Slice1 definitions.
  • Whether or not the build contains Slice2 definitions.
  • A SHA256 hash computed from the Slice files being compiled.

This data is used to help the IceRPC team understand how the tools are being used and to prioritize future development efforts. The data is stored in a private database and is not shared with any third parties.

To opt out of the build telemetry program, add the following property to your C# project file:

<PropertyGroup>
 <IceRpcBuildTelemetry>false</IceRpcBuildTelemetry>
</PropertyGroup>

Setting this property to false completely disables the computation and collection of telemetry.