CI/CD Builds for the CLR Instrumentation Engine are defined with yaml files (see build/yaml/ folder) which are leveraged by Azure DevOps pipeline builds.
Azure DevOps (previously known as Visual Studio Team Services or "VSTS") is the suite of tools and services for the end-to-end lifecycle of software development. It provides repos that host source code, task boards for work tracking, test suites and build pipelines for compiling code, and artifact management to retain packages such as nuget feeds.
Although the CLRIE repo is hosted in GitHub, it originally was hosted privately by Microsoft and leveraged Azure DevOps pipelines to build and release packages for internal consumption. In the spirit of Open-Source, these processes are slowly being rolled out publicly to expand and share ownership with external partners and users.
Although the build agents and tasks are internal, the build definitions are declared in the repo in the form of yaml files.
The yaml files are located in the
- Pipelines – The top level yaml file that is queued for a given Azure DevOps build. A pipeline defines the jobs to run.
- PR-Yaml points to build/yaml/pipelines/PR.yaml
- CI-Yaml points to build/yaml/pipelines/CI.yaml
- (Internal) ClrInstrumentationEngine-Signed-Yaml points build/yaml/pipelines/Signed.yaml
- Jobs – A job represents the execution boundary of a set of steps on an agent machine.
- The three high-level jobs include Binaries.yaml, Test.yaml, and Packages.yaml.
- Jobs/Binaries.yaml and Jobs/Packages.yaml reference the corresponding files in the Windows and Linux folders for parallelization
- Steps – The task to run (eg. Nuget restore, msbuild solution, copy files).
We restrict access of running the above builds to Microsoft and close contributors as to avoid malicious code from running. The signed build requires internal processes (signing and security checks) and will not be exposed to the public. If you require modifications or changes to the build, you are free to update the yaml files.
Please contact clrieowners@microsoft.com regarding questions or requesting the release of a new version. This process involves regression testing with both our internal Microsoft products as well as the products of external partners.
On Windows we use MSBuild, with .vcxproj files to build native binaries and .csproj files to build the NuGet/Zip packages.
- Install Visual Studio 2022 with the following Workloads and Components:
- [Workload] .NET desktop development
- [Workload] Desktop development with C++
- [Component] Windows 10 SDK (latest)
- [Component] C++ ATL for latest v143 build tools with Spectre Mitigations (x86 & x64)
- [Component] MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)
- Open
InstrumentationEngine.slnandsrc/InstrumentationEngine.Packages.slnin Visual Studio 2022 - Either run "Build Solution" for a single configuration, or "Build > Batch Build..." to build all configurations (Debug|Release with x86|x64|AnyCPU).
Alternatively, you may run the script [CLRInstrumentationEngine repo]\build.ps1 in PowerShell which conducts a local build.
| Flag | Description |
|---|---|
| IncludeTests | Runs unit tests after build. |
| SkipBuild | Skips building the solutions. Use this with -IncludeTests flag to only run tests. |
| SkipPackaging | Skips building the package solution. This prevents generating zip files, nugets, and any other artifacts. |
| SkipCleanAndRestore | Skips cleaning the bin/ & obj/ folders before building. This saves time when rebuilding due to small changes. |
| Release | Cause build to run with Release configuration. By default, build uses Debug configuration. |
| VerboseMsbuild | Sets msbuild verbosity to normal. By default, verbosity is set to ErrorsOnly. |
If you encounter this error:
*.pdb was generated by the linker with /DEBUG:fastlink; compiler cannot update such PDB files; please delete it or use /Fd to specify a different PDB filename
Please clean the solution or delete the bin folder and then try building again.
Currently we are not ready for external partners to build for Linux.
On Linux we use CMake, with CMakeLists.txt files in each native component's root folder. Build using the script /src/build.sh. Note that we
have some limitations for now:
- Cannot generate InstrumentationEngine.h yet, therefore...
- It is necessary to build your corresponding flavor/architecture in Windows first so that InstrumentationEngine.h is generated by midl and placed on the expected path.
- We only support compiling for 64bit Linux and only support specific versions of Alpine, Ubuntu, and Debian.
- NuGet package building is currently not implemented.
Since the CLRIE contains C++ code that depends on a mix of C++ standard functions (eg. wprintf) and Windows-specific functions (eg. GetEnvironmentVariable from winbase.h), we leverage the same library that the dotnet Core CLR uses to compile on Linux: the Platform Abstraction Layer or "PAL".
WARNING: If you attempt to build on Linux, you may see a CoreCLRPAL package. This package is customized to support a subset of the PAL which is used by some internal Microsoft products including the CLRIE. We offer no guarantees or warranties as to the correctness of this package and can update at our own discretion based on the needs of our products and features. We strongly encourage users to generate their own package from the dotnet Core CLR repo instead.