Skip to content

Commit 975ffe9

Browse files
jasonginjasongin
authored
Document steps for testing a private build (#202)
1 parent de21e54 commit 975ffe9

5 files changed

+67
-11
lines changed

‎Directory.Build.props

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
<LangVersion>12</LangVersion>
77
<Nullable>enable</Nullable>
88
<Configuration Condition="'$(Configuration)'==''">Debug</Configuration>
9+
<PackRelease>false</PackRelease><!-- Prevent `dotnet pack` from defaulting to Release config. -->
910
<BaseOutputPath>$(MSBuildThisFileDirectory)out/</BaseOutputPath>
1011
<OutputPath>$(BaseOutputPath)bin/$(Configuration)/$(MSBuildProjectName)/</OutputPath>
1112
<PackageOutputPath>$(BaseOutputPath)pkg/</PackageOutputPath>

‎README-DEV.md

+56-6
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
- _and_ [.NET 6 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0)
66
- _and_ [.NET 4.7.2 developer pack](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net472)
77
(Windows only)
8-
- [Node.js](https://nodejs.org/) version 16 or later
8+
- [Node.js](https://nodejs.org/) version 18 or later
99

1010
While `node-api-dotnet` supports .NET 6 or .NET Framework 4 at runtime, .NET 8 or later SDK is
1111
required for building the AOT components.
@@ -21,10 +21,11 @@ from re-using a previously-loaded (possibly outdated) version of the source gene
2121

2222
## Build Packages
2323
```bash
24-
dotnet pack -c Release
24+
dotnet pack
2525
```
2626
This produces both nuget and npm packages (for the current platform only) in the `out/pkg`
27-
directory.
27+
directory. It uses `Debug` configuration by default, which is slower but allows for
28+
[debugging](#debugging). Append `-c Relase` to change the configuration.
2829

2930
## Test
3031
```bash
@@ -50,16 +51,60 @@ assembly, then all `.js` test files execute against the assembly.
5051
Most test cases run twice, once for "hosted" CLR mode and once for AOT ahead-of-time compiled mode
5152
with no CLR.
5253

54+
### Test a Private Build in another project
55+
A project typically consumes the `Microsoft.JavaScript.NodeApi` packages from `nuget.org`. Use these
56+
steps to set up a project to use a local build of the packages instead:
57+
1. [Build nuget packages](#build-packages) with `dotnet pack`.
58+
2. Note the version of the packages produced. If building from branch other than `main` the
59+
package version may include a git commit hash.
60+
3. Add the package output directory to `<packageSources>` in your project's `NuGet.config` file,
61+
before the `nuget.org` package source. It should look like this. (Replace
62+
`/path/to-/node-api-dotnet` with the correct relative or absolute path on your system.)
63+
```xml
64+
<?xml version="1.0" encoding="utf-8"?>
65+
<configuration>
66+
<packageSources>
67+
<clear />
68+
<add key="local" value="/path/to/node-api-dotnet/out/pkg" />
69+
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
70+
</packageSources>
71+
<disabledPackageSources>
72+
<clear />
73+
</disabledPackageSources>
74+
</configuration>
75+
```
76+
4. In your `.csproj` or `Directory.Packages.props` file, update `<PackageReference>` elements to
77+
reference the version of the packages that you built locally. Include the git commit hash suffix,
78+
if applicable. For example:
79+
```xml
80+
<ItemGroup>
81+
<PackageReference Include="Microsoft.JavaScript.NodeApi" Version="0.4.31-g424705b2aa" />
82+
<PackageReference Include="Microsoft.JavaScript.NodeApi.Generator" Version="0.4.31-g424705b2aa" />
83+
</ItemGroup>
84+
```
85+
5. Stop the .NET build server to ensure it doesn't continue using a previous version of the
86+
generator assembly:
87+
```bash
88+
dotnet build-server shutdown
89+
```
90+
5391
## Debugging
5492
With a debug build, the following environment variables trigger just-in-time debugging of the
5593
respective components:
5694
- `NODE_API_DEBUG_GENERATOR=1` - Debug the C# source-generator or TS type-definitions generator
57-
when they runs during the build.
95+
when they run during the build.
5896
- `NODE_API_DEBUG_RUNTIME=1` - Debug the .NET runtime host when it is loaded by JavaScript. (Does
5997
not apply to AOT-compiled modules.)
98+
6099
Setting either of these variables to `1` causes the program to print a message to the console
61-
at startup and wait for a debugger to attach. Set to the string `vs` to use the VS JIT
62-
Debug dialog instead (requires Windows and a Visual Studio installation).
100+
at startup and wait (with 20s countdown) for a debugger to attach:
101+
```
102+
###################### DEBUG ######################
103+
Process "node" (21864) is waiting for debugger.
104+
Press any key to continue without debugging... (20)
105+
```
106+
Set to the string `vs` to use the VS JIT Debug dialog instead. (Requires Windows and a Visual Studio
107+
installation.)
63108

64109
## Tracing
65110
The following environment variables trigger verbose tracing to the console:
@@ -74,5 +119,10 @@ PR builds will fail if formatting does not comply with settings in `.editorconfi
74119
dotnet format --severity info --verbosity detailed
75120
```
76121

122+
## Benchmarks
123+
There are a lot of micro-benchmarks to measure low-level .NET/JS interop operations. See
124+
[bench/README.md](./bench/README.md) for details.
125+
77126
## Roadmap
127+
We track major feature work on the project board:
78128
[node-api-dotnet tasks](https://github.com/users/jasongin/projects/1/views/1)

‎bench/Directory.Build.props

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
<Project>
2+
<!-- The main purpose of this file is to prevent use of the root Directory.Build.props file,
3+
because Benchmark.NET does not like the build output paths to be redirected. -->
24
<PropertyGroup>
3-
<LangVersion>10</LangVersion>
5+
<TargetFrameworks Condition=" '$(TargetFrameworks)' == '' and ! $([MSBuild]::IsOsPlatform('Windows')) ">net8.0</TargetFrameworks>
6+
<TargetFrameworks Condition=" '$(TargetFrameworks)' == '' and $([MSBuild]::IsOsPlatform('Windows')) ">net8.0;net472</TargetFrameworks>
7+
<LangVersion>12</LangVersion>
48
<Nullable>enable</Nullable>
9+
<PackRelease>false</PackRelease>
10+
<SuppressNETCoreSdkPreviewMessage>true</SuppressNETCoreSdkPreviewMessage>
511
</PropertyGroup>
6-
712
</Project>

‎bench/NodeApi.Bench.csproj

-3
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
11
<Project Sdk="Microsoft.NET.Sdk">
22

33
<PropertyGroup>
4-
<TargetFrameworks Condition=" '$(TargetFrameworks)' == '' and ! $([MSBuild]::IsOsPlatform('Windows')) ">net8.0</TargetFrameworks>
5-
<TargetFrameworks Condition=" '$(TargetFrameworks)' == '' and $([MSBuild]::IsOsPlatform('Windows')) ">net8.0;net472</TargetFrameworks>
64
<OutputType>exe</OutputType>
75
<RootNamespace>Microsoft.JavaScript.NodeApi.Bench</RootNamespace>
86
<IsPackable>false</IsPackable>
97
<IsPublishable>false</IsPublishable>
108
<NoWarn>MSB3270</NoWarn><!-- Processor architecture mismatch bewteen "MSIL" and ... -->
11-
<SuppressNETCoreSdkPreviewMessage>true</SuppressNETCoreSdkPreviewMessage>
129
</PropertyGroup>
1310

1411
<ItemGroup>

‎bench/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ This project contains a set of micro-benchmarks for .NET + JS interop operations
44
[BenchmarkDotNet](https://benchmarkdotnet.org/). Most benchmarks run in both CLR and AOT modes,
55
though the "Dynamic" benchmarks are CLR-only.
66

7+
> :warning: The benchmarks currently depend on a special branch build of `libnode` being present at
8+
`../bin/<rid>`. This should be resolved with [#107](https://github.com/microsoft/node-api-dotnet/issues/107).
9+
710
### Run all benchmarks
811
```
912
dotnet run -c Release -f net8.0 --filter *

0 commit comments

Comments
 (0)