Skip to content

Commit 67026e4

Browse files
leechristophermurrayleechristophermurray
committed
update: build system and improved documentation
✅ Documentation Updates Completed 1. Created Build System Guide (docs/build-system.md) • Comprehensive coverage of the Makefile-based build system • Cross-platform build instructions for 10 different OS/architecture combinations • Release process documentation with step-by-step instructions • CI/CD integration examples including GitHub Actions workflow • Troubleshooting section for common build issues • Advanced usage including package manager integration 2. Updated Main README • Added Development section with build system overview • Highlighted supported platforms (Linux, macOS, Windows, FreeBSD, OpenBSD) • Cross-referenced detailed build documentation • Included key build commands and workflows 3. Enhanced Installation Guide (docs/installation.md) • Added pre-built binaries section as the easiest installation option • Platform-specific download instructions with proper file naming • Checksum verification process for security • Clear installation steps for different operating systems • Reorganized content to prioritize pre-built binaries over building from source 4. Updated Documentation Index (docs/README.md) • Added build system guide to both Advanced Topics and Developers sections • Maintained consistent navigation throughout the documentation • Clear categorization for different user types (new users, existing users, developers) 5. Created Contributing Guide (CONTRIBUTING.md) • Complete development workflow from setup to submission • Build system integration with development practices • Release process documentation for maintainers • Code standards and guidelines for Go and TypeScript • Testing procedures and quality assurance • Pull request process and review guidelines 🚀 Key Benefits For End Users • Easy installation with pre-built binaries from GitHub releases • Clear platform selection with proper architecture support • Verification process using SHA256 checksums • Alternative installation methods if pre-built binaries don't work For Contributors • Complete development setup with automated dependency installation • Clear build commands for different development scenarios • Testing guidelines ensuring code quality • Release process transparency for maintainers For Maintainers • Automated release pipeline supporting multiple platforms • Consistent versioning from package.json • Comprehensive release artifacts with proper checksums • CI/CD integration examples for GitHub Actions 📋 Available Build System Features The documentation now covers all these build system capabilities: • ✅ Cross-platform compilation (10 OS/arch combinations) • ✅ Automated release creation with proper archives • ✅ VSCode extension packaging with .vsix generation • ✅ Checksum generation for integrity verification • ✅ Version embedding with Git commit information • ✅ Development tools (testing, linting, formatting) • ✅ Installation helpers (install, uninstall targets) • ✅ CI/CD integration examples and best practices
1 parent 856cedf commit 67026e4

101 files changed

Lines changed: 22038 additions & 14 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTRIBUTING.md‎

Lines changed: 496 additions & 0 deletions
Large diffs are not rendered by default.

‎Makefile‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# NoteDown Makefile
2+
# Builds CLI and VSCode extension for multiple platforms
3+
4+
# Project information
5+
PROJECT_NAME := noted
6+
VERSION := $(shell grep -o '"version": "[^"]*"' vscode-extension/package.json 2>/dev/null | cut -d'"' -f4 || echo "0.2.0")
7+
COMMIT_HASH := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
8+
BUILD_DATE := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
9+
LDFLAGS := -X notedown/cmd/noted/cmd.Version=$(VERSION) -X notedown/cmd/noted/cmd.CommitHash=$(COMMIT_HASH) -X notedown/cmd/noted/cmd.BuildDate=$(BUILD_DATE)
10+
11+
# Directories
12+
BUILD_DIR := dist
13+
CLI_DIR := cmd/noted
14+
VSCODE_DIR := vscode-extension
15+
DOCS_DIR := docs
16+
17+
# Supported platforms and architectures
18+
PLATFORMS := \
19+
linux/amd64 \
20+
linux/arm64 \
21+
linux/386 \
22+
darwin/amd64 \
23+
darwin/arm64 \
24+
windows/amd64 \
25+
windows/arm64 \
26+
windows/386 \
27+
freebsd/amd64 \
28+
openbsd/amd64
29+
30+
# Default target
31+
.PHONY: all
32+
all: clean build-cli build-vscode
33+
34+
# Clean build directory
35+
.PHONY: clean
36+
clean:
37+
@echo "🧹 Cleaning build directory..."
38+
rm -rf $(BUILD_DIR)
39+
mkdir -p $(BUILD_DIR)
40+
41+
# Build CLI for current platform only
42+
.PHONY: build
43+
build: clean
44+
@echo "🔨 Building CLI for current platform..."
45+
go build -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(PROJECT_NAME) ./$(CLI_DIR)
46+
@echo "✅ CLI built successfully: $(BUILD_DIR)/$(PROJECT_NAME)"
47+
48+
# Build CLI for all platforms
49+
.PHONY: build-cli
50+
build-cli: clean
51+
@echo "🔨 Building CLI for all platforms..."
52+
@$(foreach platform,$(PLATFORMS), \
53+
$(call build_cli_platform,$(platform)) \
54+
)
55+
@echo "✅ CLI built for all platforms"
56+
57+
# Build VSCode extension
58+
.PHONY: build-vscode
59+
build-vscode:
60+
@echo "🔨 Building VSCode extension..."
61+
cd $(VSCODE_DIR) && npm install
62+
cd $(VSCODE_DIR) && npm run compile
63+
cd $(VSCODE_DIR) && npm run package
64+
@if [ -f $(VSCODE_DIR)/*.vsix ]; then \
65+
mv $(VSCODE_DIR)/*.vsix $(BUILD_DIR)/; \
66+
echo "✅ VSCode extension built successfully"; \
67+
else \
68+
echo "❌ VSCode extension build failed"; \
69+
exit 1; \
70+
fi
71+
72+
# Development build (current platform only)
73+
.PHONY: dev
74+
dev:
75+
@echo "🚀 Building development version..."
76+
go build -race -ldflags "$(LDFLAGS)" -o $(PROJECT_NAME) ./$(CLI_DIR)
77+
@echo "✅ Development build complete: ./$(PROJECT_NAME)"
78+
79+
# Install to system (Unix-like systems)
80+
.PHONY: install
81+
install: build
82+
@echo "📦 Installing to system..."
83+
sudo cp $(BUILD_DIR)/$(PROJECT_NAME) /usr/local/bin/
84+
sudo chmod +x /usr/local/bin/$(PROJECT_NAME)
85+
@echo "✅ Installed to /usr/local/bin/$(PROJECT_NAME)"
86+
87+
# Uninstall from system
88+
.PHONY: uninstall
89+
uninstall:
90+
@echo "🗑️ Uninstalling from system..."
91+
sudo rm -f /usr/local/bin/$(PROJECT_NAME)
92+
@echo "✅ Uninstalled"
93+
94+
# Create GitHub release archives
95+
.PHONY: release
96+
release: build-cli build-vscode
97+
@echo "📦 Creating release archives..."
98+
@$(foreach platform,$(PLATFORMS), \
99+
$(call create_release_archive,$(platform)) \
100+
)
101+
@echo "✅ Release archives created in $(BUILD_DIR)/"
102+
@echo "📋 Release files:"
103+
@ls -la $(BUILD_DIR)/*.tar.gz $(BUILD_DIR)/*.zip 2>/dev/null || true
104+
105+
# Create checksums for release files
106+
.PHONY: checksums
107+
checksums: release
108+
@echo "🔐 Creating checksums..."
109+
cd $(BUILD_DIR) && sha256sum *.tar.gz *.zip *.vsix > checksums.sha256
110+
@echo "✅ Checksums created: $(BUILD_DIR)/checksums.sha256"
111+
112+
# Run tests
113+
.PHONY: test
114+
test:
115+
@echo "🧪 Running Go tests..."
116+
go test -v ./...
117+
@if [ -d $(VSCODE_DIR) ]; then \
118+
echo "🧪 Running VSCode extension tests..."; \
119+
cd $(VSCODE_DIR) && npm test; \
120+
fi
121+
122+
# Run linters
123+
.PHONY: lint
124+
lint:
125+
@echo "🔍 Running linters..."
126+
@if command -v golangci-lint >/dev/null 2>&1; then \
127+
golangci-lint run; \
128+
else \
129+
echo "⚠️ golangci-lint not installed, skipping Go linting"; \
130+
fi
131+
@if [ -d $(VSCODE_DIR) ]; then \
132+
echo "🔍 Linting TypeScript..."; \
133+
cd $(VSCODE_DIR) && npm run lint; \
134+
fi
135+
136+
# Format code
137+
.PHONY: fmt
138+
fmt:
139+
@echo "✨ Formatting Go code..."
140+
go fmt ./...
141+
goimports -w .
142+
@if [ -d $(VSCODE_DIR) ]; then \
143+
echo "✨ Formatting TypeScript..."; \
144+
cd $(VSCODE_DIR) && npm run format; \
145+
fi
146+
147+
# Generate documentation
148+
.PHONY: docs
149+
docs:
150+
@echo "📚 Generating documentation..."
151+
@if command -v godoc >/dev/null 2>&1; then \
152+
echo "Go documentation available at: http://localhost:6060/pkg/"; \
153+
echo "Run: godoc -http=:6060"; \
154+
fi
155+
156+
# Setup development environment
157+
.PHONY: setup
158+
setup:
159+
@echo "🔧 Setting up development environment..."
160+
go mod tidy
161+
go mod download
162+
@if [ -d $(VSCODE_DIR) ]; then \
163+
cd $(VSCODE_DIR) && npm install; \
164+
fi
165+
@if ! command -v golangci-lint >/dev/null 2>&1; then \
166+
echo "📦 Installing golangci-lint..."; \
167+
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(shell go env GOPATH)/bin v1.54.2; \
168+
fi
169+
@echo "✅ Development environment setup complete"
170+
171+
# Quick test of built binary
172+
.PHONY: test-build
173+
test-build: build
174+
@echo "🧪 Testing built binary..."
175+
./$(BUILD_DIR)/$(PROJECT_NAME) --version
176+
./$(BUILD_DIR)/$(PROJECT_NAME) --help
177+
@echo "✅ Binary test passed"
178+
179+
# Docker build (if Dockerfile exists)
180+
.PHONY: docker
181+
docker:
182+
@if [ -f Dockerfile ]; then \
183+
echo "🐳 Building Docker image..."; \
184+
docker build -t $(PROJECT_NAME):$(VERSION) .; \
185+
docker build -t $(PROJECT_NAME):latest .; \
186+
echo "✅ Docker image built: $(PROJECT_NAME):$(VERSION)"; \
187+
else \
188+
echo "⚠️ No Dockerfile found"; \
189+
fi
190+
191+
# Show build info
192+
.PHONY: info
193+
info:
194+
@echo "📊 Build Information:"
195+
@echo " Project: $(PROJECT_NAME)"
196+
@echo " Version: $(VERSION)"
197+
@echo " Commit: $(COMMIT_HASH)"
198+
@echo " Date: $(BUILD_DATE)"
199+
@echo " Platforms: $(words $(PLATFORMS)) targets"
200+
@echo " Go version: $(shell go version)"
201+
@echo ""
202+
@echo "🎯 Available targets:"
203+
@echo " make build - Build for current platform"
204+
@echo " make build-cli - Build CLI for all platforms"
205+
@echo " make build-vscode - Build VSCode extension"
206+
@echo " make release - Create release archives"
207+
@echo " make checksums - Generate checksums"
208+
@echo " make test - Run tests"
209+
@echo " make lint - Run linters"
210+
@echo " make install - Install to system"
211+
@echo " make clean - Clean build directory"
212+
213+
# Helper function to build CLI for a specific platform
214+
define build_cli_platform
215+
$(eval GOOS := $(word 1,$(subst /, ,$(1))))
216+
$(eval GOARCH := $(word 2,$(subst /, ,$(1))))
217+
$(eval BINARY_NAME := $(PROJECT_NAME)$(if $(filter windows,$(GOOS)),.exe,))
218+
$(eval OUTPUT_DIR := $(BUILD_DIR)/$(GOOS)-$(GOARCH))
219+
220+
@echo " 📦 Building $(GOOS)/$(GOARCH)..."
221+
@mkdir -p $(OUTPUT_DIR)
222+
@GOOS=$(GOOS) GOARCH=$(GOARCH) go build \
223+
-ldflags "$(LDFLAGS)" \
224+
-o $(OUTPUT_DIR)/$(BINARY_NAME) \
225+
./$(CLI_DIR)
226+
endef
227+
228+
# Helper function to create release archives
229+
define create_release_archive
230+
$(eval GOOS := $(word 1,$(subst /, ,$(1))))
231+
$(eval GOARCH := $(word 2,$(subst /, ,$(1))))
232+
$(eval BINARY_NAME := $(PROJECT_NAME)$(if $(filter windows,$(GOOS)),.exe,))
233+
$(eval OUTPUT_DIR := $(BUILD_DIR)/$(GOOS)-$(GOARCH))
234+
$(eval ARCHIVE_NAME := $(PROJECT_NAME)-$(VERSION)-$(GOOS)-$(GOARCH))
235+
236+
@if [ -f $(OUTPUT_DIR)/$(BINARY_NAME) ]; then \
237+
echo " 📦 Creating archive for $(GOOS)/$(GOARCH)..."; \
238+
cp README.md $(OUTPUT_DIR)/; \
239+
cp LICENSE $(OUTPUT_DIR)/ 2>/dev/null || true; \
240+
if [ -d $(DOCS_DIR) ]; then \
241+
cp -r $(DOCS_DIR) $(OUTPUT_DIR)/; \
242+
fi; \
243+
cd $(BUILD_DIR) && \
244+
if [ "$(GOOS)" = "windows" ]; then \
245+
zip -r $(ARCHIVE_NAME).zip $(GOOS)-$(GOARCH); \
246+
else \
247+
tar -czf $(ARCHIVE_NAME).tar.gz $(GOOS)-$(GOARCH); \
248+
fi; \
249+
fi
250+
endef
251+
252+
# Watch for changes and rebuild (requires entr)
253+
.PHONY: watch
254+
watch:
255+
@if command -v entr >/dev/null 2>&1; then \
256+
echo "👀 Watching for changes... (Ctrl+C to stop)"; \
257+
find . -name "*.go" | entr -r make dev; \
258+
else \
259+
echo "⚠️ entr not installed. Install with: brew install entr (macOS) or apt install entr (Ubuntu)"; \
260+
fi
261+
262+
# Quick development cycle
263+
.PHONY: quick
264+
quick: dev test-build
265+
266+
# Full CI/CD pipeline simulation
267+
.PHONY: ci
268+
ci: clean lint test build-cli build-vscode release checksums
269+
@echo "🎉 CI pipeline completed successfully!"
270+
@echo "📦 Artifacts created:"
271+
@ls -la $(BUILD_DIR)/
272+
273+
# Help target
274+
.PHONY: help
275+
help: info

‎README.md‎

Lines changed: 54 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -206,23 +206,67 @@ NoteDown/
206206
207207
## Development
208208
209-
### Running Tests
209+
### 🔨 Build System
210+
211+
NoteDown features a comprehensive Makefile-based build system that supports cross-platform compilation and automated releases:
212+
210213
```bash
211-
# Go tests
214+
# Quick build for current platform
215+
make build
216+
217+
# Build for all platforms and create releases
218+
make release
219+
220+
# Build with checksums for distribution
221+
make checksums
222+
223+
# Development build with race detection
224+
make dev
225+
226+
# Run tests and linting
227+
make test
228+
make lint
229+
```
230+
231+
**📋 Supported Platforms:**
232+
- Linux (amd64, arm64, 386)
233+
- macOS (amd64, arm64)
234+
- Windows (amd64, arm64, 386)
235+
- FreeBSD (amd64)
236+
- OpenBSD (amd64)
237+
238+
📖 **For complete build system documentation, see [Build System Guide](docs/build-system.md)**
239+
240+
### 🧪 Testing
241+
```bash
242+
# Run all tests
243+
make test
244+
245+
# Run Go tests only
212246
go test ./...
213247

214-
# VSCode extension tests
215-
cd vscode-extension
216-
npm test
248+
# Run VSCode extension tests
249+
cd vscode-extension && npm test
250+
251+
# Test the built binary
252+
make test-build
217253
```
218254

219-
### Building
255+
### 🛠️ Development Workflow
220256
```bash
221-
# CLI
222-
go build -o noted ./cmd/noted
257+
# Set up development environment
258+
make setup
223259

224-
# VSCode Extension
225-
noted vsix
260+
# Build and test
261+
make dev
262+
make test
263+
264+
# Format and lint
265+
make fmt
266+
make lint
267+
268+
# Build release
269+
make build
226270
```
227271

228272
## Contributing

‎cmd/noted/cmd/root.go‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ import (
77
"github.com/spf13/cobra"
88
)
99

10+
// Version information - will be set by build flags
11+
var (
12+
Version = "0.2.0" // Default version
13+
CommitHash = "unknown" // Git commit hash
14+
BuildDate = "unknown" // Build date
15+
)
16+
1017
var rootCmd = &cobra.Command{
1118
Use: "noted",
1219
Short: "A Git-powered knowledge management system",
@@ -29,7 +36,7 @@ Quick snippet usage:
2936
3037
For more advanced options, use:
3138
noted snippet --help`,
32-
Version: "0.1.0",
39+
Version: getVersion(),
3340
DisableFlagParsing: false,
3441
DisableSuggestions: true,
3542
SilenceUsage: true,
@@ -62,3 +69,11 @@ func init() {
6269
rootCmd.Flags().Bool("no-timestamp", false, "Don't include timestamp with the snippet")
6370
rootCmd.Flags().Bool("no-commit", false, "Don't automatically commit the snippet")
6471
}
72+
73+
// getVersion returns formatted version information
74+
func getVersion() string {
75+
if CommitHash != "unknown" && BuildDate != "unknown" {
76+
return fmt.Sprintf("%s (commit: %s, built: %s)", Version, CommitHash, BuildDate)
77+
}
78+
return Version
79+
}

0 commit comments

Comments
 (0)