personotes/docs/FREEBSD_BUILD.md

Guide de Build pour FreeBSD

Prérequis

Installation de Go sur FreeBSD

# Installer Go depuis les packages
pkg install go

# Ou compiler depuis les ports
cd /usr/ports/lang/go && make install clean

# Vérifier l'installation
go version

Clonage du projet

# Cloner le repository
git clone https://github.com/mathieu/project-notes.git
cd project-notes

# Vérifier que tous les fichiers Go sont présents
find . -name "*.go" | sort

Fichiers Go requis :

./cmd/server/main.go                    # Point d'entrée principal
./internal/api/daily_notes.go           # Gestion des notes quotidiennes
./internal/api/favorites.go             # API des favoris
./internal/api/handler.go               # Handler HTTP principal
./internal/api/handler_test.go          # Tests unitaires
./internal/api/rest_handler.go          # API REST
./internal/indexer/indexer.go           # Indexation et recherche
./internal/indexer/indexer_test.go      # Tests indexeur
./internal/watcher/watcher.go           # Surveillance fichiers

Build

1. Télécharger les dépendances

go mod download

Dépendances requises :

• github.com/fsnotify/fsnotify v1.7.0 - Surveillance système de fichiers
• gopkg.in/yaml.v3 v3.0.1 - Parsing YAML front matter
• golang.org/x/sys v0.4.0 - API système (indirect)

2. Vérifier les dépendances

go mod tidy

Note : Si go mod tidy ne produit aucune sortie, c'est normal ! Cela signifie que le fichier go.mod est déjà à jour.

3. Compiler

# Compilation standard
go build -o server ./cmd/server

# Avec optimisations
go build -ldflags="-s -w" -o server ./cmd/server

# Build statique (recommandé pour FreeBSD)
CGO_ENABLED=0 go build -ldflags="-s -w" -o server ./cmd/server

4. Vérifier le binaire

file ./server
./server --help

Lancement

Mode développement

# Lancer directement avec go run
go run ./cmd/server

# Ou avec le binaire compilé
./server

Le serveur démarre sur http://localhost:8080

Mode production

# Copier le binaire
cp server /usr/local/bin/project-notes

# Créer un utilisateur dédié
pw useradd -n notes -c "Project Notes" -d /var/notes -s /usr/sbin/nologin

# Créer le dossier de notes
mkdir -p /var/notes/notes
chown -R notes:notes /var/notes

# Lancer avec l'utilisateur dédié
su -m notes -c '/usr/local/bin/project-notes'

Dépannage

Problème : go mod tidy ne fait rien

C'est normal ! Si go mod tidy ne produit aucune sortie et retourne immédiatement, cela signifie que :

• Toutes les dépendances sont déjà listées dans go.mod
• Aucune dépendance inutilisée n'est présente
• Le fichier go.sum est à jour

Pour vérifier que tout est OK :

# Vérifier les dépendances
go list -m all

# Télécharger les dépendances si nécessaire
go mod download

# Compiler pour vérifier
go build ./cmd/server

Problème : Erreurs de compilation

# Nettoyer le cache
go clean -cache -modcache -testcache

# Re-télécharger les dépendances
go mod download

# Recompiler
go build ./cmd/server

Problème : Dépendances manquantes

# Vérifier que go.mod et go.sum sont présents
ls -la go.mod go.sum

# Re-synchroniser
go mod tidy
go mod download

Problème : Fichiers Go manquants

Si des fichiers .go sont manquants, c'était dû à un bug dans le .gitignore qui ignorait le dossier cmd/server/.

Vérifié et corrigé ! Le .gitignore a été corrigé pour utiliser /server au lieu de server, ce qui ignore uniquement le binaire à la racine et non le dossier source.

Vérifier que tous les fichiers sont présents :

git ls-files | grep -E '\.(go|mod|sum)$'

Devrait afficher 11 fichiers (1 go.mod, 1 go.sum, 9 fichiers .go).

Tests

# Lancer tous les tests
go test ./...

# Tests avec verbosité
go test -v ./...

# Tests avec couverture
go test -cover ./...

# Tests d'un package spécifique
go test -v ./internal/api
go test -v ./internal/indexer

Optimisations FreeBSD

1. Build statique

Pour éviter les dépendances dynamiques :

CGO_ENABLED=0 GOOS=freebsd GOARCH=amd64 go build -ldflags="-s -w" -o server ./cmd/server

2. Service rc.d

Créer /usr/local/etc/rc.d/project_notes :

#!/bin/sh
#
# PROVIDE: project_notes
# REQUIRE: NETWORKING
# KEYWORD: shutdown

. /etc/rc.subr

name="project_notes"
rcvar="project_notes_enable"
command="/usr/local/bin/project-notes"
command_args=""
pidfile="/var/run/${name}.pid"
project_notes_user="notes"
project_notes_chdir="/var/notes"

load_rc_config $name
run_rc_command "$1"

Activer au démarrage :

chmod +x /usr/local/etc/rc.d/project_notes
sysrc project_notes_enable="YES"
service project_notes start

3. Surveillance avec daemon(8)

daemon -p /var/run/project-notes.pid -u notes -r /usr/local/bin/project-notes

Architecture du projet

project-notes/
├── cmd/
│   └── server/
│       └── main.go              # Point d'entrée
├── internal/
│   ├── api/                     # Handlers HTTP
│   │   ├── handler.go           # Handler principal
│   │   ├── rest_handler.go      # API REST
│   │   ├── daily_notes.go       # Notes quotidiennes
│   │   ├── favorites.go         # Favoris
│   │   └── handler_test.go      # Tests
│   ├── indexer/                 # Recherche full-text
│   │   ├── indexer.go
│   │   └── indexer_test.go
│   └── watcher/                 # Surveillance fichiers
│       └── watcher.go
├── frontend/                    # Frontend Vite
├── static/                      # Assets statiques
├── templates/                   # Templates HTML
├── notes/                       # Notes Markdown
├── go.mod                       # Dépendances Go
├── go.sum                       # Checksums
└── README.md                    # Documentation

Vérification finale

# Tous les fichiers sont présents ?
git ls-files | grep -E '\.(go|mod|sum)$' | wc -l
# Doit afficher : 11

# Compilation réussie ?
go build -o server ./cmd/server && echo "✅ Build OK"

# Tests passent ?
go test ./... && echo "✅ Tests OK"

# Binaire fonctionne ?
./server &
sleep 2
curl http://localhost:8080/ && echo "✅ Server OK"
pkill -f ./server

Support

Pour toute question ou problème de build sous FreeBSD, vérifier :

1. Version de Go : go version (minimum 1.22)
2. Variables d'environnement : go env
3. Fichiers présents : git status et git ls-files
4. Logs de compilation : go build -v ./cmd/server

---

Dernière mise à jour : 11 novembre 2025 Testé sur : FreeBSD 13.x et 14.x Version Go minimale : 1.22