Getting Started with NDepend on Linux and macOS
The primary goal of using NDepend.Console.MultiOS.dll on macOS or Linux is to generate code quality reports from a CI/CD pipeline. See some sample reports below.. We have plans to integrate with IDEs on macOS and Linux (Visual Studio for Mac, Rider, VS Code...) but we are not there yet.
To run NDepend on macOS or Linux pre-installating .NET 7.0 or .NET 6.0 or .NET 5.0 is required. It can be downloaded from the official Microsoft page.
Then download the NDepend zip redistributable that works on Windows, Linux and macOS. It is recommended to unzip the NDepend files in the /home/$user$/ndepend folder. This way no permission access exception should be thrown.
./net7.0/NDepend.Console.MultiOS.dll is a net7.0 cross-platform dll with entry point.
> dotnet ~/ndepend/net7.0/NDepend.Console.MultiOS.dll RegEval
More information about report generation in the section Run an analysis and build a report below. Notice that on Linux and macOS the 4 diagrams are not yet generated.
Such report can be produced by invoking NDepend.Console.exe $absolute-path-to-an-NDepend-project-file$ from your build process, on Windows, Linux and Mac.
Such report can also be produced through the NDepend GitHub Action.
NDepend.Console.MultiOS.dll can also be used to to:
- Register evaluation or a license
- Create an NDepend Project File
- Integration with a CI/CD system
- Use the same NDepend project on various OS.
- Run the NDepend PowerTools that are explained here.
- Run your own program based on NDepend.API as explained here.
Registering evaluation or a license on a Linux or macOS machine
NDepend.Console.MultiOS.dll can be used with these arguments to register or unregister NDepend on a Linux or macOS machine (case-insensitive):
- --RegEval : Start the NDepend 14 days evaluation on the current machine.
- --RegLic XYZ : Register a seat of the license key XYZ on the current machine. Notice that the license XYZ must be a Build Machine license to run NDepend.Console.MultiOS.dll.
- --UnregLic : Unregister a seat of the license key already registered on the current machine.
- --RefreshLic : Refresh the license data already registered on the current machine. This is useful when the license changes upon renewal.
A switch can be used as-is like RegEval or preceded by variousindicator like /RegEval, -RegEval or --RegEval.
Each of these operation requires internet access to do a roundtrip with the NDepend server. If the current machine doesn't have internet access, a procedure is proposed to complete the operation by accessing manually the NDepend server from a connected machine.
Notice that on Windows, a license key registered from NDepend v2021.1 (or lower) doesn't work with v2021.2 (or upper) NDepend.Console.MultiOS.dll.
In such situation the license must be registered again from v2021.2 (or upper) through:
The reason is that .NET Core only supports Rijndael encryption algorithm with a block size of 128 bits while we used to rely on 256 bits in NDepend v2021.1 and lower (as shown in .NET Core source code).
Create a Project File with NDepend.Console.MultiOS
NDepend.Console.MultiOS.dll can be used to create an NDepend project file (.ndproj extension). This is useful to create NDepend project(s) on-the-fly from a script.
Here are arguments required to created a project with NDepend.Console.exe:
- The first argument must be --CreateProject or -cp (case-insensitive).
- The second argument must be the project file path to create. The file name must have the extension .ndproj. If you need to specify a path that contains a space character use double quotes "...". The specified path can be either an absolute Linux or macOS path (like "/mnt/c/dir/MyProjectFile.ndproj"), a path relative to the current directory (obtained with System.Environment.CurrentDirectory), or a file name in the current directory.
Then at least one or several sources of code to analyze must be precised. A source of code to analyze can be:
A path to a Visual Studio solution file.
The solution file extension must be .sln.
The vertical line character '|' can follow the path to declare a filter on project names (as explained in this section). If no filter is precised the default filter -test is defined. If you need to specify a path or a filter that contains a space character use double quotes "...".
Example: "..\My File\MySolution.sln|filterIn -filterOut".
A path to a Visual Studio project file. The project file extension must be within: .csproj .vbproj .proj
A path to a compiled assembly file. The compiled assembly file extension must be within: .dll .exe .winmd
Notice that source of code paths can be absolute or relative to the project file location.
If you need to specify a path or a filter that contains a space character use double quotes "...".
Here is a short example that illustrates arguments to create a project:
>dotnet ~/ndepend/net7.0/NDepend.Console.MultiOS.dll -cp /mnt/c/temp/ndepend/MyProj.ndproj "../src/MySolution.sln|-filter" "/mnt/c/My Dir/MyAssembly1.dll" /mnt/c/MyDir/MyAssembly2.dll
To modify the various properties of an NDepend project file created with NDepend.Console.exe.MultiOS the options are:
Running an analysis and build a report on a Linux or macOS machine
NDepend.Console.MultiOS.dll can be used to run an NDepend analysis and build a report on a Linux or macOS machine.
The path to the input .ndproj NDepend project file.
It must be specified as the first argument. If you need to specify a path that contains a space character use double quotes ".. ..". The specified path can be either an absolute Linux or macOS path (like "/mnt/c/dir/MyProjectFile.ndproj"), a path relative to the current directory (obtained with System.Environment.CurrentDirectory), or a file name in the current directory.
NDepend.Console.MultiOS.dll accepts several optional arguments to override various aspects of the analysis from the command line (help; historic analysis results; force log trend metrics; compare with a baseline; output dir; silent; view report...).
These optional arguments are listed in the ./NDepend.Console.exe documentation that accepts the same optional arguments.
Integration within a CI/CD system
NDepend analysis can be performed from any CI/CD system to pass the rules of an NDepend project, pass quality gates and build a report.
To do so ~/ndepend/net7.0/NDepend.Console.MultiOS.dll must be invoked from a CI/CD task. The previous section explains how to invoke NDepend.Console.MultiOS.dll.
Since NDepend consumes .NET assemblies built by the compilation in DEBUG mode (see explanations here), and eventually code coverage files built at test time (see explanations here), the NDepend analysis must be fired after the compilation and eventually after tests execution under coverage.
|Notice that NDepend.Console.MultiOS.dll returns a non-zero exit code when at least one Quality Gate fails. This exit code can be used to eventually stop your build process in such situation.|
Use the same NDepend project on various OS
Windows absolute paths are formatted like "C:\Dir" and "\\Server\Share" while Linux or macOS absolute paths are formatted like "/mnt/c/dir/". Thus absolute paths are compatible between Linux and macOS, but incompatible with Windows (and vice-versa). As a consequence if a NDepend project or analysis result is aimed to be used on various OS there are a few caveats:
- If an NDepend project is used on various OS, it must reference only relative paths. These paths are then relative to the NDepend project file location.
- When using NDepend.Console.MultiOS.dll (or NDepend.Console.exe on Windows) to create a project, absolute paths provided are transformed to relative paths when possible.
As explained in the documentation Understanding NDepend Analysis Inputs the primary sources of code analyzed are .NET assemblies, their PDB files and the source files referenced by the PDB files.
When compiling an assembly, the PDB files are referencing absolute source files paths with the format of the underlying OS. NDepend extracts and stores these absolute paths in the analysis results it produces.
As a consequence if an NDepend analysis result is consumed on a various OS, (for example an analysis result produced on Linux is opened with VisualNDepend.exe on Windows) the absolute source file paths that it contain are incompatible and cannot be used to locate or open the source file path.
However an NDepend analysis result stores all source files analyzed zipped. Even when the absolute paths are OS incompatible, the source files can still be unzipped and even compared between two analysis results.