Skip to content

Latest commit

 

History

History
244 lines (168 loc) · 6.4 KB

BUILDING.md

File metadata and controls

244 lines (168 loc) · 6.4 KB
Raw

Building from source

Use the build shell script to build the source code in this repository:

Linux or macOS

./build.sh --help

Windows

build.cmd -help

Table of contents

Prerequisites

  1. Rust
    Install Rust using rustup.

  2. .NET SDK 8.0
    Download the .NET SDK from dotnet.microsoft.com.

  3. docfx (optional)
    The IceRRC API reference is generated by docfx. You can install docfx as follows:

    dotnet tool update -g docfx

  4. ReportGenerator (optional)
    The code coverage reports are generated by ReportGenerator. You can install ReportGenerator as follows:

    dotnet tool install -g dotnet-reportgenerator-globaltool

Build roadmap

flowchart LR
    compiler(slicec-cs) --> slice-tools(IceRpc.Slice.Tools) --> icerpc(ZeroC.Slice<br>IceRpc.*)
    protobuf-tools(IceRpc.Protobuf.Tools) --> icerpc
    icerpc -- doc --> api(API reference)
    icerpc -- publish --> nuget(NuGet packages) --> examples(Examples)
    icerpc --> tests(Tests) -- coverage --> cov(Code coverage reports)
Loading

The Slice compiler for C# (slicec-cs) is written in Rust. Everything else is written in C#.

Building IceRpc

Command line

Linux or macOS

./build.sh --build

Windows

build.cmd -build

This command builds all the tools, sources and tests with the default config (debug).

The -build/--build action is optional since it's the default build action.

Visual Studio Code

Select Tasks: Run Build Task... from the command palette to run the build script from Visual Studio Code.

Running the tests

C# tests

dotnet test

This command executes all tests known to the IceRpc.sln solution. See dotnet-test for additional options.

Rust tests

cd tools/slicec-cs
cargo test

This command runs the test suite for slicec-cs.

Creating and publishing NuGet packages

Linux or macOS

./build.sh --publish

Windows

build.cmd -publish

This command creates all the NuGet packages and publishes them to your local global-packages source.

Note This is an essential step if you want to use a local build with the examples.

Slice tools

By default, the NuGet package IceRpc.Slice.Tools includes only the slicec-cs compiler created by the local build.

If you set the MSBuild property SLICEC_CS_STAGING_PATH, IceRpc.Slice.Tools instead includes the slicec-cs compiler for all supported platforms. The expected layout of the staging directory is <os-name>-<os-arch>/<compiler-executable>, with the following subdirectories:

  • linux-x64: Linux x86_64
  • linux-arm64: Linux ARM64
  • macos-x64: macOS x86_64
  • macos-arm64: macOS Apple silicon
  • windows-x64: Windows x64

Make sure that all these compilers are available when you set SLICEC_CS_STAGING_PATH.

Generating the API reference

Linux or macOS

./build.sh --doc

Windows

build.cmd -doc

This command generates the API reference into the docfx\_site directory. Start a local web server to view this API reference:

docfx serve docfx/_site

Generating the code coverage reports

Linux or macOS

./build.sh --coverage

Windows

build.cmd -coverage

Shutting down background MSBuild servers

You may occasionally encounter errors when cleaning and building because background MSBuild servers use/lock the IceRpc.Slice.Tools assembly. When this happens, you can shutdown these MSBuild servers with:

dotnet build-server shutdown

Updating Slice files

The slice sub-directory is managed by a Git subtree and contains the contents of the icerpc-slice repository. Updates to the files in this sub-directory must be done in the icerpc-slice repository first and then the changes can be pulled.

The procedure to upgrade these files is as follows:

  1. Open a PR (pull request) in the icerpc-slice repository with the desired changes. Once approved merge the PR in the icerpc-slice repository.

  2. Create a companion PR for the required changes in the icerpc-csharp repository. Start by creating a branch for the PR and pulling the changes from icerpc-slice:

    git checkout -b my-branch --track origin/main
git subtree pull --prefix slice git@github.com:icerpc/icerpc-slice.git main
git push <remote> my-branch

  3. Make the necessary C# updates, open the PR in icerpc-csharp, and iterate until it's ready for merging. The "Check Slice Subtree Updates" workflow job is expected to fail at this point. This is the workflow ensuring that the contents of slice sub-directory are not updated with a PR.

  4. Once you are ready to merge you need to first merge the icerpc-slice changes into the icerpc-csharp's main branch

    git checkout -b main --track origin/main
git pull
git subtree pull --prefix slice git@github.com:icerpc/icerpc-slice.git main
git push origin main

  5. Then merge the main branch into your PR

    git checkout my-branch
git merge origin/main
git push <remote> my-branch

  6. Ensure that "Check Slice Subtree Updates" workflow job passes, and that no files under slice sub-directory are modified by the PR.

  7. Finally merge your PR as usual.

Please ensure to replace <remote> with the appropriate remote repository name where you want to push your changes. Also, make sure to follow the instructions carefully, and adjust any repository and branch names as needed for your specific setup.