Skip to content

Commit e869628

Browse files
lucaspimentellucaspimentel
committed
add BUILD.md
1 parent 8fc4aeb commit e869628

1 file changed

Lines changed: 253 additions & 0 deletions

File tree

‎BUILD.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# Building and Testing
2+
3+
This document describes how to build and test the DogStatsD C# client library.
4+
5+
## Prerequisites
6+
7+
- [.NET SDK 10.0 or above](https://dotnet.microsoft.com/download)
8+
- [Docker](https://www.docker.com/get-started) (required for building Linux native libraries)
9+
10+
## Quick Start
11+
12+
```bash
13+
# Build the .NET library
14+
dotnet build
15+
16+
# Run tests for a specific framework
17+
dotnet test --framework net8.0
18+
19+
# Build all Linux native libraries using Docker
20+
./build-and-test.sh --platform linux
21+
22+
# Pack the NuGet package with all native libraries
23+
dotnet pack src/StatsdClient/StatsdClient.csproj -c Release
24+
```
25+
26+
## Building
27+
28+
### .NET Library
29+
30+
Build the main .NET library:
31+
32+
```bash
33+
# Restore dependencies
34+
dotnet restore
35+
36+
# Build all projects
37+
dotnet build
38+
39+
# Build specific project
40+
dotnet build src/StatsdClient/StatsdClient.csproj
41+
42+
# Build for specific configuration
43+
dotnet build -c Release
44+
45+
# Build for specific target framework
46+
dotnet build src/StatsdClient/StatsdClient.csproj -f netstandard2.0
47+
```
48+
49+
### Native Library (Linux only)
50+
51+
The repository includes a native C library (`libfs`) for Linux file system operations. This library must be built for multiple Linux variants to support different distributions.
52+
53+
#### Using Docker (Recommended)
54+
55+
Build all 4 Linux variants using Docker:
56+
57+
```bash
58+
# Build all variants (linux-x64, linux-musl-x64, linux-arm64, linux-musl-arm64)
59+
./build-and-test.sh --platform linux
60+
61+
# Build and test all variants
62+
./build-and-test.sh --test --platform linux
63+
```
64+
65+
**Output:** `runtimes/{rid}/native/libfs.so`
66+
67+
**Supported RIDs:**
68+
- `linux-x64` - Standard x64 Linux (glibc)
69+
- `linux-musl-x64` - Alpine x64 Linux (musl libc)
70+
- `linux-arm64` - Standard ARM64 Linux (glibc)
71+
- `linux-musl-arm64` - Alpine ARM64 Linux (musl libc)
72+
73+
#### Local Build (Linux/WSL only)
74+
75+
Build without Docker on Linux or WSL:
76+
77+
```bash
78+
# Build for specific RID (outputs to runtimes/{rid}/native/)
79+
./src/StatsdClient.Native/build.sh linux-x64
80+
81+
# Build for local development only (outputs to src/StatsdClient.Native/build/)
82+
./src/StatsdClient.Native/build.sh
83+
```
84+
85+
**Note:** Local builds compile for the current system architecture only. Docker is required to cross-compile for different architectures (x64/ARM64) or libc variants (glibc/musl).
86+
87+
## Testing
88+
89+
### Important: Framework Selection
90+
91+
**Always specify `--framework` when running tests.** Running tests without a framework specification will run all target frameworks in parallel, causing conflicts due to shared named pipes.
92+
93+
### Using build-and-test.sh
94+
95+
```bash
96+
# Test specific framework on native platform (Windows/macOS/Linux)
97+
./build-and-test.sh --test --platform native --framework net8.0
98+
99+
# Test all frameworks sequentially on native platform
100+
./build-and-test.sh --test --platform native
101+
102+
# Test all Linux variants in Docker
103+
./build-and-test.sh --test --platform linux
104+
```
105+
106+
### Using dotnet test
107+
108+
```bash
109+
# Run all tests for a specific framework
110+
dotnet test --framework net8.0
111+
112+
# Run tests for specific project and framework
113+
dotnet test tests/StatsdClient.Tests/ --framework net8.0
114+
115+
# Run only native library tests
116+
dotnet test --framework net8.0 --filter FullyQualifiedName~NativeLibraryTests
117+
118+
# Run specific test class
119+
dotnet test --framework net8.0 --filter FullyQualifiedName~DogStatsdServiceMetricsTests
120+
121+
# Run specific test method
122+
dotnet test --framework net8.0 --filter FullyQualifiedName~DogStatsdServiceMetricsTests.Counter
123+
```
124+
125+
### Testing All Frameworks Sequentially
126+
127+
**Linux/macOS:**
128+
```bash
129+
for tfm in netcoreapp2.1 netcoreapp3.0 netcoreapp3.1 net5.0 net6.0 net7.0 net8.0 net9.0 net10.0; do
130+
dotnet test --framework $tfm
131+
done
132+
```
133+
134+
**Windows (includes .NET Framework):**
135+
```bash
136+
for tfm in net48 netcoreapp2.1 netcoreapp3.0 netcoreapp3.1 net5.0 net6.0 net7.0 net8.0 net9.0 net10.0; do
137+
dotnet test --framework $tfm
138+
done
139+
```
140+
141+
Or use the build script:
142+
```bash
143+
./build-and-test.sh --test --platform native
144+
```
145+
146+
### Supported Target Frameworks
147+
148+
- .NET Framework 4.8 (Windows only)
149+
- .NET Core 2.1, 3.0, 3.1
150+
- .NET 5, 6, 7, 8, 9, 10
151+
152+
## Packaging
153+
154+
To create a NuGet package with all native libraries:
155+
156+
```bash
157+
# Step 1: Build all native library variants
158+
./build-and-test.sh --platform linux
159+
160+
# Step 2: Pack the NuGet package
161+
dotnet pack src/StatsdClient/StatsdClient.csproj -c Release
162+
163+
# Output: src/StatsdClient/bin/Release/*.nupkg
164+
```
165+
166+
The package will include all 4 Linux native library variants in the correct RID directories. The .NET runtime automatically selects the appropriate variant based on the deployment environment.
167+
168+
### Verify Package Contents
169+
170+
**Linux/WSL:**
171+
```bash
172+
unzip -l src/StatsdClient/bin/Release/DogStatsD-CSharp-Client.*.nupkg | grep libfs
173+
```
174+
175+
**Windows (PowerShell):**
176+
```powershell
177+
Expand-Archive src/StatsdClient/bin/Release/DogStatsD-CSharp-Client.*.nupkg -DestinationPath temp
178+
Get-ChildItem temp/runtimes/*/native/
179+
```
180+
181+
## Benchmarks
182+
183+
Run performance benchmarks:
184+
185+
```bash
186+
dotnet run -c Release --project benchmarks/StatsdClient.Benchmarks/StatsdClient.Benchmarks.csproj
187+
```
188+
189+
## Troubleshooting
190+
191+
### Tests fail with "address already in use" or named pipe conflicts
192+
193+
Make sure you're specifying `--framework` when running tests. Running multiple frameworks in parallel causes port and named pipe conflicts.
194+
195+
```bash
196+
# ❌ Wrong - runs all frameworks in parallel
197+
dotnet test
198+
199+
# ✅ Correct - runs single framework
200+
dotnet test --framework net8.0
201+
```
202+
203+
### Native library not found during tests
204+
205+
Ensure you've built the native libraries before running native library tests:
206+
207+
```bash
208+
./build-and-test.sh --platform linux
209+
dotnet test --framework net8.0 --filter FullyQualifiedName~NativeLibraryTests
210+
```
211+
212+
### Docker build fails on Windows
213+
214+
Make sure Docker Desktop is running and configured for Linux containers (not Windows containers).
215+
216+
### Local native build fails
217+
218+
Native library builds require:
219+
- CMake 3.10+
220+
- GCC or Clang
221+
- Standard build tools (make, etc.)
222+
223+
On Ubuntu/Debian:
224+
```bash
225+
sudo apt-get update
226+
sudo apt-get install -y cmake build-essential
227+
```
228+
229+
On Alpine:
230+
```bash
231+
apk add --no-cache cmake make gcc g++ musl-dev
232+
```
233+
234+
## Clean Build
235+
236+
Remove build artifacts:
237+
238+
```bash
239+
# Clean .NET build outputs
240+
dotnet clean
241+
242+
# Remove native library outputs
243+
rm -rf runtimes/*/native/libfs.so
244+
rm -rf src/StatsdClient.Native/build/
245+
246+
# Remove NuGet packages
247+
rm -rf src/StatsdClient/bin/ src/StatsdClient/obj/
248+
```
249+
250+
## Additional Resources
251+
252+
- [src/StatsdClient.Native/README.md](src/StatsdClient.Native/README.md) - Native library details
253+
- [.NET RID Catalog](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog) - Runtime identifier documentation

0 commit comments

Comments
 (0)