Skip to content

Commit 01bca20

Browse files
RexusRexus
committed
feat: add cross-platform Makefile with self-documenting help system
- Add comprehensive Makefile inspired by SysDocs - Self-documenting help system with organized targets - Cross-platform support (Windows/Linux/macOS) - Common targets: build, test, docker-up, docker-down, clean, etc - Advanced targets: test-coverage, format, lint, matrix generation - Simplify README.md and QUICKSTART.md to promote Make usage - Replace verbose documentation with 'make help' commands - Add docker-logs target for easier debugging - Windows-specific clean command to avoid path issues Benefits: - Single command entry point for developers (make help) - Consistent build/test/deploy across platforms - Reduces need for detailed step-by-step documentation - Improves developer experience with simple, memorable commands
1 parent 3db67b7 commit 01bca20

3 files changed

Lines changed: 283 additions & 12 deletions

File tree

‎Makefile‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Makefile for SysArx
2+
# Cross-platform build automation with self-documenting help system
3+
4+
.PHONY: help restore build test test-security test-integration test-coverage publish docker docker-up docker-down clean all reports matrix format lint verify
5+
6+
# Default configuration
7+
CONFIGURATION ?= Release
8+
SOLUTION = SysArx.sln
9+
WEB_PROJECT = src/web/SysArx.csproj
10+
AUTH_PROJECT = src/Services/Auth/Auth.csproj
11+
SYSMLSTORE_PROJECT = src/Services/SysMLStore/SysMLStore.csproj
12+
SYSMLDIAGRAM_PROJECT = src/Services/SysMLDiagram/SysMLDiagram.csproj
13+
TESTS_PROJECT = tests/SysArx.Tests/SysArx.Tests.csproj
14+
PUBLISH_DIR = publish
15+
REPORTS_DIR = reports
16+
MATRIX_SCRIPT = scripts/generate-requirements-matrix.py
17+
18+
# Detect OS for platform-specific commands
19+
ifeq ($(OS),Windows_NT)
20+
SCRIPT_EXT = .ps1
21+
SCRIPT_RUNNER = pwsh -File
22+
RM_RF = powershell -Command "Remove-Item -Recurse -Force"
23+
PYTHON = python
24+
else
25+
SCRIPT_EXT = .sh
26+
SCRIPT_RUNNER = bash
27+
RM_RF = rm -rf
28+
PYTHON = python3
29+
endif
30+
31+
help: ## Show this help message
32+
@echo "SysArx Build System"
33+
@echo "=================="
34+
@echo ""
35+
@echo "A system architecture documentation and modeling platform"
36+
@echo ""
37+
@echo "Usage: make [target]"
38+
@echo ""
39+
@echo "Common Targets:"
40+
@echo " help Show this help message"
41+
@echo " restore Restore NuGet dependencies"
42+
@echo " build Build the solution"
43+
@echo " test Run all tests"
44+
@echo " test-security Run security tests only"
45+
@echo " test-integration Run integration tests only"
46+
@echo " test-coverage Run tests with coverage"
47+
@echo " run-web Run the web application"
48+
@echo " docker Build all Docker images"
49+
@echo " docker-up Start all services with Docker Compose"
50+
@echo " docker-down Stop all Docker services"
51+
@echo " clean Clean build artifacts"
52+
@echo " all Run full build pipeline"
53+
@echo ""
54+
@echo "Advanced Targets:"
55+
@echo " publish Publish all applications"
56+
@echo " reports Generate requirements matrix"
57+
@echo " matrix Generate requirements traceability matrix"
58+
@echo " format Format code using dotnet format"
59+
@echo " lint Check code formatting"
60+
@echo " verify Verify Docker Compose configuration"
61+
@echo ""
62+
@echo "Configuration:"
63+
@echo " CONFIGURATION Build configuration (default: Release)"
64+
@echo ""
65+
@echo "Examples:"
66+
@echo " make build # Build in Release mode"
67+
@echo " make CONFIGURATION=Debug build # Build in Debug mode"
68+
@echo " make docker-up # Start all services"
69+
@echo " make test-security # Run security tests"
70+
@echo ""
71+
72+
restore: ## Restore NuGet dependencies
73+
@echo "==> Restoring dependencies..."
74+
@dotnet restore $(SOLUTION)
75+
76+
build: restore ## Build the solution
77+
@echo "==> Building solution..."
78+
@dotnet build $(SOLUTION) \
79+
--configuration $(CONFIGURATION) \
80+
--no-restore
81+
82+
test: build ## Run all tests
83+
@echo "==> Running tests..."
84+
@dotnet test $(SOLUTION) \
85+
--configuration $(CONFIGURATION) \
86+
--no-build \
87+
--verbosity normal \
88+
--logger "trx;LogFileName=test-results.trx"
89+
90+
test-security: build ## Run security tests only
91+
@echo "==> Running security tests..."
92+
@dotnet test $(SOLUTION) \
93+
--configuration $(CONFIGURATION) \
94+
--no-build \
95+
--filter "Category=Security"
96+
97+
test-integration: build ## Run integration tests only
98+
@echo "==> Running integration tests..."
99+
@dotnet test $(SOLUTION) \
100+
--configuration $(CONFIGURATION) \
101+
--no-build \
102+
--filter "Category=Integration"
103+
104+
test-coverage: build ## Run tests with code coverage
105+
@echo "==> Running tests with coverage..."
106+
@dotnet test $(SOLUTION) \
107+
--configuration $(CONFIGURATION) \
108+
--no-build \
109+
--collect:"XPlat Code Coverage" \
110+
--results-directory ./TestResults
111+
112+
run-web: build ## Run the web application
113+
@echo "==> Starting web application..."
114+
@dotnet run --project $(WEB_PROJECT) --configuration $(CONFIGURATION) --no-build
115+
116+
publish: ## Publish all applications
117+
@echo "==> Publishing applications..."
118+
@dotnet publish $(WEB_PROJECT) \
119+
--configuration $(CONFIGURATION) \
120+
--output $(PUBLISH_DIR)/web
121+
@dotnet publish $(AUTH_PROJECT) \
122+
--configuration $(CONFIGURATION) \
123+
--output $(PUBLISH_DIR)/auth
124+
@dotnet publish $(SYSMLSTORE_PROJECT) \
125+
--configuration $(CONFIGURATION) \
126+
--output $(PUBLISH_DIR)/sysmlstore
127+
@dotnet publish $(SYSMLDIAGRAM_PROJECT) \
128+
--configuration $(CONFIGURATION) \
129+
--output $(PUBLISH_DIR)/sysmldiagram
130+
@echo "==> Published to: $(PUBLISH_DIR)"
131+
132+
docker: ## Build all Docker images
133+
@echo "==> Building Docker images..."
134+
@docker build -t sysarx-web -f src/web/Dockerfile .
135+
@docker build -t sysarx-auth -f src/Services/Auth/Dockerfile .
136+
@docker build -t sysarx-sysmlstore -f src/Services/SysMLStore/Dockerfile .
137+
@docker build -t sysarx-sysmldiagram -f src/Services/SysMLDiagram/Dockerfile .
138+
@echo "==> Docker images built successfully"
139+
140+
docker-up: verify ## Start all services with Docker Compose
141+
@echo "==> Starting services with Docker Compose..."
142+
@docker compose up -d
143+
@echo "==> Services started. Access web at http://localhost:5000"
144+
145+
docker-down: ## Stop all Docker services
146+
@echo "==> Stopping Docker services..."
147+
@docker compose down
148+
@echo "==> Services stopped"
149+
150+
docker-logs: ## View Docker Compose logs
151+
@docker compose logs -f
152+
153+
verify: ## Verify Docker Compose configuration
154+
@echo "==> Verifying Docker Compose configuration..."
155+
@docker compose config > /dev/null
156+
@echo "==> Docker Compose configuration is valid"
157+
158+
clean: ## Clean build artifacts
159+
@echo "==> Cleaning build artifacts..."
160+
ifeq ($(OS),Windows_NT)
161+
@powershell -Command "Get-ChildItem -Path . -Include bin,obj -Recurse -Directory | Remove-Item -Recurse -Force" 2>nul || echo "No build artifacts to clean"
162+
@$(RM_RF) $(PUBLISH_DIR) 2>nul || echo ""
163+
@$(RM_RF) TestResults 2>nul || echo ""
164+
else
165+
@find . -type d -name bin -o -name obj | xargs $(RM_RF) 2>/dev/null || true
166+
@$(RM_RF) $(PUBLISH_DIR) 2>/dev/null || true
167+
@$(RM_RF) TestResults 2>/dev/null || true
168+
endif
169+
@echo "==> Clean complete"
170+
171+
reports: matrix ## Generate all reports
172+
173+
matrix: ## Generate requirements traceability matrix
174+
@echo "==> Generating requirements matrix..."
175+
@mkdir -p $(REPORTS_DIR)
176+
@$(PYTHON) $(MATRIX_SCRIPT)
177+
@echo "==> Requirements matrix generated: $(REPORTS_DIR)/REQUIREMENTS_MATRIX.md"
178+
179+
format: ## Format code using dotnet format
180+
@echo "==> Formatting code..."
181+
@dotnet format $(SOLUTION)
182+
183+
lint: ## Check code formatting
184+
@echo "==> Checking code formatting..."
185+
@dotnet format $(SOLUTION) --verify-no-changes
186+
187+
all: restore build test matrix ## Run full build pipeline
188+
@echo "==> Full build pipeline complete"
189+
190+
.DEFAULT_GOAL := help

‎QUICKSTART.md‎

Lines changed: 70 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,84 @@
11
# SysArx Quick Start Guide
22

3+
Get SysArx running in minutes using the built-in Makefile automation.
4+
35
## Prerequisites Check
46

57
Before starting, ensure you have:
68
- [ ] Docker Desktop installed and running
7-
- [ ] .NET 10.0 SDK installed
8-
- [ ] Dapr CLI installed (optional for local dev)
9+
- [ ] Make utility installed (comes with Git Bash on Windows, or use `winget install GnuWin32.Make`)
10+
- [ ] .NET 10.0 SDK (optional, only for local development)
11+
12+
> 💡 **Tip**: Run `make help` at any time to see all available commands
913
10-
## Quick Start with Docker
14+
## Quick Start with Make
1115

1216
1. **Clone and navigate to the project:**
13-
2. **Start all services with Docker Compose:**
1417
```bash
15-
docker-compose up --build
18+
git clone https://github.com/CodeOOf/SysArx.git
19+
cd SysArx
20+
```
21+
22+
2. **See all available commands:**
23+
```bash
24+
make help
25+
```
26+
27+
3. **Start all services with Docker Compose:**
28+
```bash
29+
make docker-up
1630
```
1731

18-
3. **Wait for all services to start** (approximately 2-3 minutes)
32+
4. **Wait for all services to start** (approximately 2-3 minutes)
1933

20-
4. **Access the applications:**
34+
5. **Access the applications:**
2135
- **Blazor Web UI**: http://localhost:5000
2236
- **Auth API (Swagger)**: http://localhost:5003/swagger
2337
- **SysMLStore API (Swagger)**: http://localhost:5001/swagger
2438
- **SysMLDiagram API (Swagger)**: http://localhost:5002/swagger
2539
- **Seq Logs**: http://localhost:5341
2640
- **RabbitMQ Management**: http://localhost:15672 (guest/guest)
2741

42+
## Common Make Commands
43+
44+
```bash
45+
# Build and test locally (without Docker)
46+
make build # Build the solution
47+
make test # Run all tests
48+
make test-security # Run security tests only
49+
make run-web # Start the web application locally
50+
51+
# Docker commands
52+
make docker # Build all Docker images
53+
make docker-up # Start all services
54+
make docker-down # Stop all services
55+
make docker-logs # View logs from all services
56+
57+
# Development
58+
make format # Format code
59+
make lint # Check code formatting
60+
make clean # Clean build artifacts
61+
make matrix # Generate requirements matrix
62+
63+
# Full pipeline
64+
make all # Build, test, and generate reports
65+
```
66+
67+
## Alternative: Manual Docker Compose
68+
69+
If you prefer not to use Make:
70+
71+
```bash
72+
# Start all services
73+
docker compose up -d
74+
75+
# View logs
76+
docker compose logs -f
77+
78+
# Stop all services
79+
docker compose down
80+
```
81+
2882
## Test the Authentication
2983

3084
1. **Get test users list:**
@@ -98,6 +152,15 @@ Before starting, ensure you have:
98152

99153
**Docker Compose Logs**:
100154
```bash
155+
# Using Make
156+
make docker-logs
157+
158+
# Or directly with Docker Compose
159+
docker compose logs -f
160+
161+
# Specific service
162+
docker compose logs -f web
163+
```
101164
# All services
102165
docker-compose logs -f
103166

‎README.md‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ SysArx is an open-source .NET web application for creating, visualizing, and edi
2626
- Automated test coverage with requirement tagging
2727

2828
**Getting Started**:
29-
- 🚀 [Quick Start](#quick-start) - Get running in 5 minutes
29+
- 🚀 [Quick Start](#quick-start) - Get running in 5 minutes with `make`
3030
- 🔧 [Contributing](CONTRIBUTING.md) - Start developing
3131
- 📋 [Requirements Matrix](reports/REQUIREMENTS_MATRIX.md) - Systems Engineers start here
3232
- 📖 [Full Documentation](docs/DOCUMENTATION_NAVIGATION.md)
@@ -38,17 +38,32 @@ SysArx is an open-source .NET web application for creating, visualizing, and edi
3838
### Prerequisites
3939

4040
- **Docker & Docker Compose** - Primary deployment platform
41+
- **Make** - Cross-platform build automation (recommended)
4142
- .NET 10.0 SDK (optional, for local development outside containers)
4243

43-
### Run with Docker
44+
### Run with Make (Recommended)
4445

4546
```bash
4647
# Clone the repository
4748
git clone https://github.com/CodeOOf/SysArx.git
4849
cd SysArx
4950

51+
# See all available commands
52+
make help
53+
54+
# Start all services with Docker Compose
55+
make docker-up
56+
57+
# Or build and test locally
58+
make build
59+
make test
60+
```
61+
62+
### Run with Docker Compose (Alternative)
63+
64+
```bash
5065
# Start all services (Local mode by default)
51-
docker-compose up -d
66+
docker compose up -d
5267
```
5368

5469
**Access the application:**
@@ -107,12 +122,15 @@ SysArx supports three flexible deployment modes for different team sizes and sec
107122

108123
```bash
109124
# Docker/Linux (primary deployment method)
125+
make docker-up
126+
127+
# Or using scripts
110128
./scripts/switch-mode.sh Local
111-
docker-compose up -d
129+
docker compose up -d
112130

113131
# Windows development environment
114132
scripts\switch-mode.ps1 -Mode Local
115-
docker-compose up -d
133+
docker compose up -d
116134
```
117135

118136
### 🏢 LDAP Mode (Enterprise)

0 commit comments

Comments
 (0)