Skip to content
This repository was archived by the owner on Mar 19, 2025. It is now read-only.

Commit ff61a7a

Browse files
SubPointSupportSubPointSupport
committed
+ docs
1 parent cd9b052 commit ff61a7a

File tree

1 file changed

+179
-1
lines changed

1 file changed

+179
-1
lines changed

‎README.md‎

Lines changed: 179 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,182 @@ Common cake build tools for SubPoint Solution projects.
66
| ------------- | ------------- |
77
| dev | [![Build status](https://ci.appveyor.com/api/projects/status/54i4q9hrktdhj0je/branch/dev?svg=true)](https://ci.appveyor.com/project/SubPointSupport/cakebuildtools/branch/dev) |
88
| beta | [![Build status](https://ci.appveyor.com/api/projects/status/54i4q9hrktdhj0je/branch/beta?svg=true)](https://ci.appveyor.com/project/SubPointSupport/cakebuildtools/branch/beta) |
9-
| master| [![Build status](https://ci.appveyor.com/api/projects/status/54i4q9hrktdhj0je/branch/master?svg=true)](https://ci.appveyor.com/project/SubPointSupport/cakebuildtools/branch/master) |
9+
| master| [![Build status](https://ci.appveyor.com/api/projects/status/54i4q9hrktdhj0je/branch/master?svg=true)](https://ci.appveyor.com/project/SubPointSupport/cakebuildtools/branch/master) |
10+
11+
### SubPointSolutions.CakeBuildTools in details
12+
CakeBuildTools is a high level abstraction over [Cakebuild](http://cakebuild.net) aiming to provide a highly repeatable and reusable build workflow.
13+
It is used to build [SPMeta2](https://github.com/SubPointSolutions/SPMeta2), [SPMeta2 Reverse](https://github.com/SubPointSolutions/spmeta2-reverse), [SPMeta2 VS Extensions](https://github.com/SubPointSolutions/spmeta2-vsixextensions), [SPMeta2-Spec](https://github.com/SubPointSolutions/spmeta2-spec), [MetaPack](https://github.com/SubPointSolutions/MetaPack), [DefinitelyPacked](https://github.com/SubPointSolutions/DefinitelyPacked) and [some other projects](https://github.com/SubPointSolutions) in a highly standartized way.
14+
15+
Implementation is done via cake build script which is packaged and then reused across all the builds.
16+
The aim is to hide all the complexity of the build and drive the whole build workflow via name conventions and json build configuration.
17+
18+
Current build handles:
19+
* Checking presense of environment variables
20+
* Cleaning folders
21+
* Building *.sln files
22+
* Building set of *.csproj files
23+
* Running unit tests (files and groups)
24+
* NuGet packaging and publishing
25+
* Chocolatey packaging and publishing
26+
* ZIP packaging (with checksums, part of Chocolatey packaging)
27+
28+
The following 'rules' and name conventions are encofced in order to keep the build simple:
29+
30+
#### Rule 1 - same build config for all solutions
31+
Every solution must have "Build" project housing the following files:
32+
* build.cake
33+
* build.ps1
34+
* build.json
35+
* tools/nuget.config
36+
* tools/nuget.exe
37+
* tools/packages.config
38+
* tools/packages.config.md5sum
39+
40+
nuget.config must have configuration to load up the main NuGet gallery plus both SubPoint Solution Staging and CI galleries:
41+
```xml
42+
<?xml version="1.0" encoding="utf-8"?>
43+
<configuration>
44+
<packageSources>
45+
<add key="nuget" value="https://www.nuget.org/api/v2/" />
46+
<add key="SubPointSolutions Staging" value="https://www.myget.org/F/subpointsolutions-staging/api/v2" />
47+
<add key="SubPointSolutions Appeyor CI - cakebuildtools " value="https://ci.appveyor.com/nuget/subpointsolutions-cakebuildtools" />
48+
</packageSources>
49+
</configuration>
50+
```
51+
packages.config must have at least two packages. That's how common build infrastructure gets delivered to Cake.
52+
53+
```xml
54+
<?xml version="1.0" encoding="utf-8"?>
55+
<packages>
56+
<package id="Cake" version="0.17.0" />
57+
<package id="SubPointSolutions.CakeBuildTools" version="0.1.0-alpha170521456" />
58+
</packages>
59+
```
60+
61+
#### Rule 2 - keep the build simple
62+
Build script must delegate all work to 'SubPointSolutions.CakeBuild.Core.cake'.
63+
Use 'load' directive to load up the core build script.
64+
```
65+
// load up common tools
66+
#load tools/SubPointSolutions.CakeBuildTools/scripts/SubPointSolutions.CakeBuild.Core.cake
67+
68+
// default targets
69+
RunTarget(target);
70+
```
71+
#### Rule 3 - Default and CI builds must always pass
72+
The following builds must always pass. Use [cmder](cmder.net) in order to execute the following builds:
73+
* powershell .\build.ps1
74+
* powershell .\build.ps1 -Target Default-CI
75+
76+
#### Rule 4 - Leverage built-in tasks
77+
Common build script provides cake tasks with the following name convention:
78+
79+
* Default-XXX is a target to be used in build.ps1
80+
* Action-XXX is a self-container build task to be chained with "Default-XXX" tasks
81+
82+
83+
| Target | Actions |
84+
| ------------- | ------------- |
85+
| | Action-Docs-Publishing |
86+
| | Action-Validate-Environment |
87+
| | Action-Restore-NuGet-Packages |
88+
| Default | Action-Clean <br/> Action-Build <br/> Action-Run-UnitTests |
89+
| Default-Build | Action-Clean <br/> Action-Build |
90+
| Default-Clean | Action-Clean |
91+
| Default-Run-UnitTests | Action-Clean<br/>Action-Build<br/> Action-Run-UnitTests |
92+
| Default-API-NuGet-Packaging | Action-Clean<br/>Action-Build<br/>Action-Run-UnitTests<br/>Action-NuGet-Packaging |
93+
| Default-API-NuGet-Publishing | Action-Clean<br/>Action-Build<br/>Action-Run-UnitTests<br/>Action-API-NuGet-Packaging<br/>Action-API-NuGet-Publishing<br/> |
94+
| Default-CLI | Action-Clean<br/>Action-Build<br/>Action-Run-UnitTests<br/>Action-API-NuGet-Packaging<br/>Action-CLI-Zip-Packaging<br/>Action-CLI-Chocolatey-Packaging |
95+
| Default-CLI-Publishing | Action-Clean<br/>Action-Build<br/>Action-Run-UnitTests<br/>Action-API-NuGet-Packaging<br/>Action-CLI-Zip-Packaging<br/>Action-CLI-Chocolatey-Packaging<br/>Action-CLI-Zip-Publishing<br/>Action-CLI-Chocolatey-Publishing |
96+
| Default-Desktop | TBD |
97+
| Default-CI | Action-Clean<br/>Action-Build<br/>Action-Run-UnitTests<br/>Action-API-NuGet-Packaging<br/>Action-CLI-Zip-Packaging<br/>Action-CLI-Chocolatey-Publishing |
98+
99+
#### Rule 5 - simple build is done with build.json config
100+
All build configiration is to be driven from the build.json config.
101+
102+
The simpliest example can bve found below, and more complicated can be found in project repos at github (such as SPMeta2 and other projects).
103+
```json
104+
{
105+
"defaultSolutionDirectory": "./../",
106+
"defaultSolutionFilePath": "./../YourSolution.sln",
107+
"defaultNuGetPackagesDirectory": "./build-artifact-nuget-packages",
108+
"defaultChocolateyPackagesDirectory": "./build-artifact-cli-packages",
109+
"defaultNuspecVersion": "0.1.0",
110+
111+
"defaultTestCategories": [
112+
"CI.Core"
113+
],
114+
"customNuspecs": [
115+
116+
],
117+
"customChocolateySpecs": [
118+
119+
],
120+
"defaultTestAssemblyPaths": [
121+
122+
],
123+
"defaultBuildDirs": [ ],
124+
"defaultEnvironmentVariables": [ ]
125+
}
126+
```
127+
128+
#### Rule 6 - build customizations go with replacing default tasks
129+
Core script exposes all default/action cake tasks as global C# variables.
130+
That allows to inject custom build tasks redefining the whole build workflow.
131+
Use the following example to get started:
132+
133+
```cs
134+
135+
// load up common tools
136+
#tool nuget:https://www.myget.org/F/subpointsolutions-staging/api/v2?package=SubPointSolutions.CakeBuildTools&prerelease
137+
#load tools\SubPointSolutions.CakeBuildTools\scripts\SubPointSolutions.CakeBuild.Core.cake
138+
139+
// redefining default build task
140+
// cleaning up existing actions, adding our custom one
141+
142+
// in that case we follow all the avialable 'Default' build profiles from the core build script
143+
defaultActionBuild.Task.Actions.Clear();
144+
defaultActionBuild
145+
.Does(() =>
146+
{
147+
Information(string.Format("Building VSIX for solution:[{0}]", defaultSolutionFilePath));
148+
149+
MSBuild(defaultSolutionFilePath, settings => {
150+
151+
settings.Verbosity = Verbosity.Quiet;
152+
153+
// Building with MSBuild 12.0 fails #97
154+
// CRAZY!! to avoid the following error
155+
// error MSB4018: The "ValidateVsixManifest" task failed unexpectedly
156+
settings.ToolPath = @"C:\Program Files (x86)\MSBuild\12.0\bin\MSBuild.exe";
157+
});
158+
});
159+
160+
// filling up default build task with custom build
161+
//defaultActionBuild.Does(actionCustomBuild);
162+
163+
// default targets
164+
RunTarget(target);
165+
166+
```
167+
168+
#### Rule 7 - light appveyor.yml config
169+
appveyor.yml config must be light. Avoid adding heavy logic into it keeping it as following:
170+
171+
```
172+
test: off
173+
174+
clone_folder: c:\prj
175+
176+
build_script:
177+
- ps: c:\prj\Build\build.ps1 -Target "Default-CI" -Verbosity Minimal
178+
179+
artifacts:
180+
- path: '**\packages\*.nupkg'
181+
```
182+
183+
#### Rule 8 - find examples in other projects
184+
Check dev branches of other SubPoint Solution projects to get more understanding on how common build works and can be configured.
185+
186+
### Known issues
187+
* Appveyor build may somehow chacnge MD5 checksum of packages.config. Disable it in build.ps1

0 commit comments

Comments
 (0)