|
3 | 3 | This repository contains Akka.NET serializers that implements compression. |
4 | 4 |
|
5 | 5 | Currently, it contains these serializers: |
6 | | -- [Akka.Serialization.Compressed.Json](src/Akka.Serialization.Compressed.Json) - a compressed version of the built-in `Akka.Serialization.NewtonSoftJsonSerializer`. |
| 6 | +- [Akka.Serialization.Compressed.Json](src/Akka.Serialization.Compressed.Json) - a compressed version of the built-in `Akka.Serialization.NewtonSoftJsonSerializer`. You can read the documentation for this serializer [here](./src/Akka.Serialization.Compressed.Json/README.md) |
7 | 7 |
|
8 | | -# The Build System |
| 8 | +# Building This Project |
9 | 9 |
|
10 | | -This build system is powered by [NUKE](https://nuke.build/); please see their [API documentation](https://nuke.build/docs/getting-started/philosophy.html) should you need to make any changes to the `Build.cs` file. |
11 | | - |
12 | | -To install Nuke GlobalTool and SignClient, execute the following command at the root of this folder: |
13 | | - |
14 | | -``` |
15 | | -build.cmd |
16 | | -``` |
17 | | - |
18 | | -## GitHub Actions `yml` auto-generation |
19 | | - |
20 | | -You can define your GitHub workflows in code and Nuke will generate the YAML files for you. |
21 | | - |
22 | | -You can update or add to what exist in `Build.CI.GitHubActions.cs` (`AutoGenerate` has to be set to true): |
23 | | - |
24 | | -```csharp |
25 | | -[CustomGitHubActions("pr_validation", |
26 | | - GitHubActionsImage.WindowsLatest, |
27 | | - GitHubActionsImage.UbuntuLatest, |
28 | | - AutoGenerate = true, |
29 | | - OnPushBranches = new[] { "master", "dev" }, |
30 | | - OnPullRequestBranches = new[] { "master", "dev" }, |
31 | | - CacheKeyFiles = new[] { "global.json", "src/**/*.csproj" }, |
32 | | - InvokedTargets = new[] { nameof(Tests) }, |
33 | | - PublishArtifacts = true) |
34 | | -] |
35 | | -[CustomGitHubActions("Windows_release", |
36 | | - GitHubActionsImage.WindowsLatest, |
37 | | - AutoGenerate = true, |
38 | | - OnPushBranches = new[] { "refs/tags/*" }, |
39 | | - InvokedTargets = new[] { nameof(NuGet) }, |
40 | | - ImportSecrets = new[] { "Nuget_Key" }, |
41 | | - PublishArtifacts = true) |
42 | | -] |
43 | | - |
44 | | -``` |
45 | | -To generate or update existing workflow yaml file(s), execute any of the commands (e.g. `build.cmd compile`): |
46 | | - |
47 | | -```shell |
48 | | -PS C:\Users\user\source\repos\Akka.Serialization.Compressed> .\build.cmd compile |
49 | | -PowerShell Desktop version 5.1.19041.1320 |
50 | | -Microsoft (R) .NET Core SDK version 6.0.101 |
51 | | -11:42:25 [INF] Creating directory C:\Users\user\source\repos\Akka.Serialization.Compressed\.github\workflows... |
52 | | -11:42:25 [INF] Creating directory C:\Users\user\source\repos\Akka.Serialization.Compressed\.github\workflows... |
53 | | -11:42:28 [WRN] Configuration files for GitHubActions (Windows_release) have changed. |
54 | | -11:42:28 [WRN] Configuration files for GitHubActions (pr_validation) have changed. |
55 | | -Press any key to continue ... |
56 | | - |
57 | | -███╗ ██╗██╗ ██╗██╗ ██╗███████╗ |
58 | | -████╗ ██║██║ ██║██║ ██╔╝██╔════╝ |
59 | | -██╔██╗ ██║██║ ██║█████╔╝ █████╗ |
60 | | -██║╚██╗██║██║ ██║██╔═██╗ ██╔══╝ |
61 | | -██║ ╚████║╚██████╔╝██║ ██╗███████╗ |
62 | | -╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝ |
63 | | - |
64 | | -``` |
65 | | - |
66 | | -## Supported Build System Commands |
67 | | - |
68 | | -This project comes with some ready-made commands, all of which can be listed via: |
69 | | - |
70 | | -``` |
71 | | - build.cmd help |
72 | | -``` |
73 | | -If you desire to add more commands, please see the [Fundamentals](https://nuke.build/docs/authoring-builds/fundamentals.html). |
74 | | - |
75 | | -### Summary |
76 | | - |
77 | | -The ready-made commands you can start working with (both on **Windows** and **Linux**), are detailed as follows: |
78 | | - |
79 | | -* `build.cmd Install` - installs `Nuke.GlobalTool` and `SignClient` - which is the default when no command is passed. |
80 | | -* `build.cmd all` - runs the following commands: `BuildRelease`, `RunTests`, `NBench` and `Nuget`. |
81 | | -* `build.cmd compile` - compiles the solution in `Release` mode. The default mode is `Release`, to compile in `Debug` mode => `--configuration debug` |
82 | | -* `build.cmd buildrelease` - compiles the solution in `Release` mode. |
83 | | -* `build.cmd runtests` - compiles the solution in `Release` mode and runs the unit test suite (all projects that end with the `.Tests.csproj` suffix). All of the output will be published to the `./TestResults` folder. |
84 | | -* `build.cmd nbench` - compiles the solution in `Release` mode and runs the [NBench](https://nbench.io/) performance test suite (all projects that end with the `.Tests.Performance.csproj` suffix). All of the output will be published to the `./PerfResults` folder. |
85 | | -* `build.cmd nuget` - compiles the solution in `Release` mode and creates Nuget packages from any project that does not have `<IsPackable>false</IsPackable>` set and uses the version number from `RELEASE_NOTES.md`. |
86 | | -* `build.cmd nuget --nugetprerelease dev` - compiles the solution in `Release` mode and creates Nuget packages from any project that does not have `<IsPackable>false</IsPackable>` set - but in this instance all projects will have a `VersionSuffix` of `-beta{DateTime.UtcNow.Ticks}`. It's typically used for publishing nightly releases. |
87 | | -* `build.cmd nuget --SignClientUser $(signingUsername) --SignClientSecret $(signingPassword)` - compiles the solution in `Release` modem creates Nuget packages from any project that does not have `<IsPackable>false</IsPackable>` set using the version number from `RELEASE_NOTES.md`, and then signs those packages using the SignClient data below. |
88 | | -* `build.cmd nuget --SignClientUser $(signingUsername) --SignClientSecret $(signingPassword) --nugetpublishurl $(nugetUrl) --nugetkey $(nugetKey)` - compiles the solution in `Release` modem creates Nuget packages from any project that does not have `<IsPackable>false</IsPackable>` set using the version number from `RELEASE_NOTES.md`, signs those packages using the SignClient data below, and then publishes those packages to the `$(nugetUrl)` using NuGet key `$(nugetKey)`. |
89 | | -* `build.cmd DocFx` - compiles the solution in `Release` mode and then uses [DocFx](http://dotnet.github.io/docfx/) to generate website documentation inside the `./docs/_site` folder. Use the `build.cmd servedocs` on Windows to preview the documentation. |
90 | | - |
91 | | -This build script is powered by [NUKE](https://nuke.build/); please see their API documentation should you need to make any changes to the [`build.cs`](/build/build.cs) file. |
92 | | - |
93 | | -### Release Notes, Version Numbers, Etc |
94 | | -This project will automatically populate its release notes in all of its modules via the entries written inside [`RELEASE_NOTES.md`](RELEASE_NOTES.md) and will automatically update the versions of all assemblies and NuGet packages via the metadata included inside [`Directory.Build.props`](src/Directory.Build.props). |
95 | | - |
96 | | -**RELEASE_NOTES.md** |
97 | | -``` |
98 | | -#### [0.1.0] / October 05 2019 #### |
99 | | -First release |
100 | | -``` |
101 | | - |
102 | | -In this instance, the NuGet and assembly version will be `0.1.0` based on what's available at the top of the `RELEASE_NOTES.md` file. |
103 | | - |
104 | | -**RELEASE_NOTES.md** |
105 | | -``` |
106 | | -#### [0.1.0] / October 05 2019 #### |
107 | | -First release |
108 | | -``` |
109 | | - |
110 | | -But in this case the NuGet and assembly version will be `0.1.0`. |
111 | | - |
112 | | -### Conventions |
113 | | -The attached build script will automatically do the following based on the conventions of the project names added to this project: |
114 | | - |
115 | | -* Any project name ending with `.Tests` will automatically be treated as a [XUnit2](https://xunit.github.io/) project and will be included during the test stages of this build script; |
116 | | -* Any project name ending with `.Tests.Performance` will automatically be treated as a [NBench](https://github.com/petabridge/NBench) project and will be included during the test stages of this build script; and |
117 | | -* Any project meeting neither of these conventions will be treated as a NuGet packaging target and its `.nupkg` file will automatically be placed in the `bin\nuget` folder upon running the `build.cmd all` command. |
118 | | - |
119 | | -### DocFx for Documentation |
120 | | -This solution also supports [DocFx](http://dotnet.github.io/docfx/) for generating both API documentation and articles to describe the behavior, output, and usages of your project. |
121 | | - |
122 | | -All of the relevant articles you wish to write should be added to the `/docs/articles/` folder and any API documentation you might need will also appear there. |
123 | | - |
124 | | -All of the documentation will be statically generated and the output will be placed in the `/docs/_site/` folder. |
125 | | - |
126 | | -#### Previewing Documentation |
127 | | -To preview the documentation for this project, execute the following command at the root of this folder: |
128 | | - |
129 | | -``` |
130 | | -build.cmd servedocs |
131 | | -``` |
132 | | - |
133 | | -This will use the built-in `docfx.console` binary that is installed as part of the NuGet restore process from executing the above command to preview the fully-rendered documentation. For best results, do this immediately after calling `build.cmd compile`. |
134 | | - |
135 | | -### Code Signing via SignService |
136 | | -This project uses [SignService](https://github.com/onovotny/SignService) to code-sign NuGet packages prior to publication. The `build.cmd` scripts will automatically download the `SignClient` needed to execute code signing locally on the build agent, but it's still your responsibility to set up the SignService server per the instructions at the linked repository. |
137 | | - |
138 | | -Once you've gone through the ropes of setting up a code-signing server, you'll need to set a few configuration options in your project in order to use the `SignClient`: |
139 | | - |
140 | | -* Add your Active Directory settings to [`appsettings.json`](appsettings.json) and |
141 | | -* Pass in your signature information to the `SigningName`, `SigningDescription`, and `SigningUrl` values inside `build.cs`. |
142 | | - |
143 | | -Whenever you're ready to run code-signing on the NuGet packages published by `build.cs`, execute the following command: |
144 | | - |
145 | | -``` |
146 | | -build.cmd signpackages --SignClientSecret {your secret} --SignClientUser {your username} |
147 | | -``` |
148 | | - |
149 | | -This will invoke the `SignClient` and actually execute code signing against your `.nupkg` files prior to NuGet publication. |
| 10 | +The build documentation can be read [here](./BUILD.md) |
0 commit comments