The repository provides a layered Git integration:
- Public OO wrapper over libgit2:
src/fpdev.git2.pas - Modern interfaces (recommended for new code):
src/git2.api.pas+ adapter implsrc/git2.impl.pas - C API bindings (libgit2):
src/libgit2.pas
Notes:
fpdev.git2exposes concrete classes (TGitManager/TGitRepository/...) and keeps a compatibility shimTGit2Manager.- New code should prefer
git2.api+git2.impl(interfaces first, easy to replace backends). Existing code can continue to usefpdev.git2safely. fpdev.git(system git command wrapper) is deprecated; libgit2 path is the preferred backend.
-
Recommended imports in applications/tests:
- Preferred:
uses git2.api, git2.impl;thenNewGitManager()to obtainIGitManager - Compatible:
uses fpdev.git2;thenGitManagersingleton orTGitManager.Create - Only import
libgit2when you must call the C API directly
- Preferred:
-
Build (Lazarus is on PATH):
lazbuild --build-all --no-write-project test_libgit2_simple.lpilazbuild --build-all --no-write-project test_libgit2_complete.lpilazbuild --build-all --no-write-project tests\test_git2_adapter.lpilazbuild --build-all --no-write-project tests\test_ssl_toggle.lpilazbuild --build-all --no-write-project tests\test_offline_repo.lpi
-
Runtime requirement (Windows): Ensure
git2.dllis discoverable (next to the executable or in PATH).
# Help & version
fpdev help
fpdev version
# FPC management
fpdev fpc install 3.2.2 # Binary installation (default, fast)
fpdev fpc install 3.2.2 --from-source # Source installation (customizable)
fpdev fpc install 3.2.2 --offline # Offline mode (cache-only, no network)
fpdev fpc install 3.2.2 --no-cache # Force fresh download (ignore cache)
fpdev fpc list --all
fpdev fpc list --remote # List versions from manifest
fpdev fpc use 3.2.2 # Activate version (alias: default)
fpdev fpc current
fpdev fpc show 3.2.2
fpdev fpc verify 3.2.2 # Verify installation with smoke test
fpdev fpc clean 3.2.2 # clean build artifacts from source
fpdev fpc update 3.2.2 # update FPC sources (git pull)
# Manifest management
fpdev fpc update-manifest # Download and cache latest manifest
fpdev fpc update-manifest --force # Force refresh manifest cache
# Cache management
fpdev fpc cache list # List all cached versions
fpdev fpc cache stats # Show cache statistics
fpdev fpc cache clean 3.2.2 # Clean specific version
fpdev fpc cache clean --all # Clean all cached versions
fpdev fpc cache path # Show cache directory path
# Lazarus management
fpdev lazarus install 3.0 --from-source
fpdev lazarus list
fpdev lazarus use 3.0 # alias: default
fpdev lazarus current
fpdev lazarus run
# Cross toolchains
fpdev cross list --all
fpdev cross install win64
fpdev cross configure win64 --binutils=C:/bin --libraries=C:/lib
# Packages
fpdev package install synapse
fpdev package list --all
fpdev package search json
fpdev package repo add custom https://example.com/repo
fpdev package repo remove custom # alias: rm, del
fpdev package repo list # alias: ls
# Projects
fpdev project new console hello-world
fpdev project list
fpdev project build
fpdev project clean # clean build artifacts
fpdev project run # run built executable
fpdev project test # run project testsExposes modern OO wrappers around libgit2:
TGitManager: lifecycle & helpers (Initialize/Finalize, OpenRepository, CloneRepository, InitRepository, DiscoverRepository, Get/Set config, GetVersion, VerifySSL)TGitRepository: open/clone, current branch, list branches, refs/commits, fetch, simple status checksTGitCommit,TGitReference,TGitRemote,TGitSignatureandEGitError
Minimal example:
program example_simple;
{$mode objfpc}{$H+}
uses
SysUtils, fpdev.git2;
var
M: TGitManager;
R: TGitRepository;
Branches: TStringArray;
B: string;
begin
M := TGitManager.Create;
try
if not M.Initialize then
raise Exception.Create('libgit2 init failed');
// Open current working directory repo (if any)
R := M.OpenRepository('.');
try
Writeln('WorkDir: ', R.WorkDir);
Writeln('Current: ', R.GetCurrentBranch);
Writeln('Local branches:');
Branches := R.ListBranches(GIT_BRANCH_LOCAL);
for B in Branches do Writeln(' - ', B);
finally
R.Free;
end;
finally
M.Free;
end;
end.Error handling: high‑level methods raise EGitError on non‑zero returns from libgit2. Read E.Message for details.
Import libgit2 only when necessary for direct calls. The unit provides:
- Basic handles/types (git_repository, git_reference, git_commit, git_oid, etc.)
- Core functions (git_repository_open/init/head/workdir, git_reference_, git_commit_, git_branch_, git_remote_, status helpers, options init, credentials, etc.)
Example (opening a repository and reading HEAD):
uses SysUtils, libgit2;
var
Repo: git_repository;
Head: git_reference;
begin
if git_libgit2_init < 0 then Halt(1);
if git_repository_open(Repo, '.') = GIT_OK then
begin
try
if git_repository_head(Head, Repo) = GIT_OK then
Writeln('HEAD: ', git_reference_name(Head));
finally
git_repository_free(Repo);
end;
end;
git_libgit2_shutdown;
end.- Replace any
uses git2.modernwithuses fpdev.git2. - Replace any
uses libgit2_netstructsorlibgit2.dynamicwith nothing (types/options are unified inlibgit2.pas). - Where old code passed
libgit2.dynamic.git_branch_t(...), use plainGIT_BRANCH_LOCAL/REMOTE/ALLdirectly.
Build tests individually with lazbuild --build-all --no-write-project <project>.lpi. The test projects under tests/ have been cleaned to only import what they use. Warnings/hints are kept minimal by default.
- Windows: looks for
git2.dll - Linux/macOS: ensure appropriate libgit2 shared library is available (see constants in
libgit2.pasfor default names) - Compilers: tested with recent FPC trunk; adjust as needed.
- Open issues for missing libgit2 API you need. Prefer adding to
fpdev.git2first; expose C API only when necessary. - Keep the one‑unit‑per‑layer rule: high‑level in
fpdev.git2, C API inlibgit2.
FPDev 是一个类似于 Rust 的 rustup 的现代化 FreePascal 开发环境管理工具,为 FreePascal 和 Lazarus 开发者提供完整的工具链管理解决方案。
- 🔧 多版本管理: FPC 和 Lazarus 多版本并存,一键切换
- 🌐 交叉编译: 支持 12 个主流平台的交叉编译工具链
- 📦 包管理: 类似 npm/cargo 的包管理体验
- 🚀 项目模板: 7 种内置项目模板,快速创建标准化项目
- ⚙️ 统一配置: JSON 格式配置文件,类型安全访问
- 🏗️ 源码构建: 从 Git 仓库自动下载和编译最新版本
✅ 功能完整性: 100% (Phase 1, Phase 2 & Phase 4.2 完成)
✅ 测试覆盖率: 100% (44+个测试用例,11个测试套件)
✅ 文档完整性: 100% (8个文档页面)
✅ 跨平台支持: Windows, Linux, macOS
✅ 代码质量: 生产就绪
✅ 安装模式: 二进制/源码双模式 (Phase 2.2)
✅ 作用域管理: 项目/用户级安装 (Phase 2.1)
✅ 激活系统: Shell脚本 + VS Code (Phase 2.4)
✅ Bootstrap 管理: 自动下载 + 跨平台支持 (Phase 4.2)
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/fpdev/fpdev/releases/download/v1.0.0/fpdev-windows-x64.zip" -OutFile "fpdev.zip"
Expand-Archive -Path "fpdev.zip" -DestinationPath "C:\fpdev"
# Linux
wget https://github.com/fpdev/fpdev/releases/download/v1.0.0/fpdev-linux-x64.tar.gz
tar -xzf fpdev-linux-x64.tar.gz && sudo mv fpdev /usr/local/bin/
# macOS
curl -L -o fpdev-macos.tar.gz https://github.com/fpdev/fpdev/releases/download/v1.0.0/fpdev-macos-x64.tar.gz
tar -xzf fpdev-macos.tar.gz && sudo mv fpdev /usr/local/bin/# 1. 安装 FPC 3.2.2
fpdev fpc install 3.2.2 --from-source
# 2. 安装 Lazarus 3.0
fpdev lazarus install 3.0 --from-source
# 3. 创建新项目
fpdev project new console hello-world
cd hello-world
# 4. 构建项目
fpdev project build
# 5. 运行项目
fpdev project run
# 或直接运行: ./hello-world (Linux/macOS) / hello-world.exe (Windows)
# 6. 清理构建产物
fpdev project clean
# 7. 运行测试(如果有)
fpdev project test# 二进制安装(默认,快速)
fpdev fpc install 3.2.2
# 源码安装(可自定义编译选项)
fpdev fpc install 3.2.2 --from-source
# 注意:源码安装时会自动下载所需的 bootstrap 编译器
# 支持平台:Win32/64, Linux32/64, macOS (x86_64/ARM64)
# 项目作用域安装(安装到 .fpdev/toolchains/)
cd myproject
fpdev fpc install 3.2.2
# 自定义安装路径
fpdev fpc install 3.2.2 --prefix=/custom/path
# 列出所有版本
fpdev fpc list --all
# 激活版本(设置为默认并生成激活脚本)
fpdev fpc use 3.2.2
# 验证安装(版本检查 + hello.pas 编译测试)
fpdev fpc verify 3.2.2
# 显示当前版本
fpdev fpc current
# 清理源码构建产物
fpdev fpc clean 3.2.2
# 更新FPC源码 (git pull)
fpdev fpc update 3.2.2激活后会生成 shell 激活脚本和 VS Code 配置:
# 激活版本
fpdev fpc use 3.2.2
# 在当前 shell 中激活(项目作用域)
.fpdev\env\activate.cmd # Windows
source .fpdev/env/activate.sh # Linux/macOS
# 或者用户作用域激活
%USERPROFILE%\.fpdev\env\activate-3.2.2.cmd # Windows
source ~/.fpdev/env/activate-3.2.2.sh # Linux/macOS
# VS Code 会自动使用 .vscode/settings.json 中的路径配置清理源码构建产物 (fpdev fpc clean)
- 递归清理所有
.o,.ppu,.a,.so等编译产物 - 保留源代码文件和 Git 仓库
- 释放磁盘空间,为重新编译做准备
# 清理特定版本的构建产物
fpdev fpc clean 3.2.2
# 示例输出:
# Cleaning FPC 3.2.2 build artifacts...
# Removed: 1234 object files (.o)
# Removed: 567 unit files (.ppu)
# Removed: 89 library files (.a, .so)
# Total freed: 456 MB
# Source repository preserved更新 FPC 源码 (fpdev fpc update)
- 执行
git pull更新源码到最新版本 - 自动检测是否需要重新编译
- 保留本地配置和构建设置
# 更新特定版本的源码
fpdev fpc update 3.2.2
# 示例输出:
# Updating FPC 3.2.2 sources...
# Running: git pull origin fixes_3_2
# Already up to date. (或显示更新的文件列表)
# Update completed successfully
# Note: Run 'fpdev fpc install 3.2.2 --from-source' to rebuild if needed典型工作流:
# 1. 更新源码到最新版本
fpdev fpc update 3.2.2
# 2. 如果有更新,清理旧的构建产物
fpdev fpc clean 3.2.2
# 3. 重新编译最新源码
fpdev fpc install 3.2.2 --from-source
# 4. 验证安装
fpdev fpc current从源码构建 FPC 时,FPDev 会自动下载并管理所需的 bootstrap 编译器:
自动化流程:
- 检测目标 FPC 版本所需的 bootstrap 版本(例如 FPC 3.2.2 需要 3.0.4)
- 优先使用系统已安装的 FPC(如果版本兼容)
- 如无兼容版本,自动从 SourceForge 下载对应平台的 bootstrap 编译器
- 下载后自动解压到
sources/fpc/bootstrap/fpc-<version>/目录 - 验证 bootstrap 编译器可用性
支持的平台:
- Windows (32-bit & 64-bit)
- Linux (32-bit & 64-bit)
- macOS (x86_64 & ARM64/Apple Silicon)
下载源:SourceForge FPC 官方镜像
用户体验:
- 完全自动化,无需手动下载或配置
- 首次构建会下载 bootstrap(约 50-100MB),后续构建重用已下载的 bootstrap
- 网络故障时会优雅降级,显示清晰的错误信息
示例输出:
$ fpdev fpc install 3.2.2 --from-source
[2/6] Checking Bootstrap compiler...
Required bootstrap version: 3.0.4
Downloading bootstrap compiler 3.0.4 from SourceForge...
Download completed: 87 MB
Extracting bootstrap compiler...
Bootstrap compiler verified: sources/fpc/bootstrap/fpc-3.0.4/bin/fpc.exe
[3/6] Cloning FPC sources...
### 2. Lazarus IDE 管理
```bash
fpdev lazarus install 3.0 --from-source # 安装 Lazarus
fpdev lazarus launch # 启动 IDE
fpdev lazarus default 3.0 # 设置默认版本
fpdev lazarus configure 3.0 # 配置 IDE(编译器路径、库路径等)fpdev lazarus configure 命令自动配置 Lazarus IDE 的编译器和库路径:
自动化配置:
- 检测已安装的 Lazarus 版本
- 查找对应的 FPC 编译器路径
- 自动配置
environmentoptions.xml文件 - 设置编译器路径、库路径、FPC 源码路径
- 创建配置备份(带时间戳)
配置内容:
- 编译器路径(CompilerFilename)
- 库路径(FPCSourceDirectory)
- FPC 源码路径(用于代码补全和调试)
用户体验:
- 完全自动化,无需手动编辑 XML 配置文件
- 自动创建备份,支持回滚
- 跨平台支持(Windows/Linux/macOS)
- 配置验证和错误提示
示例输出:
$ fpdev lazarus configure 3.0
Configuring Lazarus IDE 3.0...
Found FPC compiler: /home/user/.fpdev/fpc/3.2.2/bin/fpc
Found FPC source: /home/user/.fpdev/sources/fpc/fpc-3.2.2
Updating IDE configuration...
Backup created: /home/user/.lazarus-3.0/backups/environmentoptions_20260117_143022.xml
Configuration updated successfully!
IDE Configuration Summary:
- Compiler: /home/user/.fpdev/fpc/3.2.2/bin/fpc
- Library Path: /home/user/.fpdev/fpc/3.2.2/lib/fpc/3.2.2
- FPC Source: /home/user/.fpdev/sources/fpc/fpc-3.2.2fpdev cross list --all # 列出支持的平台
fpdev cross install win64 # 安装交叉编译目标
fpdev cross configure win64 --binutils=/path --libraries=/pathfpdev package install synapse # 安装包
fpdev package list --all # 列出包
fpdev package repo add custom https://example.com/repofpdev project new console myapp # 创建控制台应用
fpdev project new gui myapp # 创建 GUI 应用
fpdev project list # 列出可用模板
fpdev project build # 构建项目
fpdev project clean # 清理构建产物 (.o, .ppu, .exe等)
fpdev project run [args] # 运行已构建的可执行文件
fpdev project test # 运行项目测试 (test*.exe)- JSON 格式配置文件
- 类型安全的配置访问
- 工具链、版本、交叉编译目标统一管理
# 显示帮助信息
fpdev help
# 显示版本信息
fpdev version
# FPC 相关操作
fpdev fpc install 3.2.2 # 安装 FPC 3.2.2
fpdev fpc list # 列出已安装的 FPC 版本
fpdev fpc default 3.2.2 # 设置默认 FPC 版本
# Lazarus 相关操作
fpdev lazarus install 3.0 # 安装 Lazarus 3.0
fpdev lazarus list # 列出已安装的 Lazarus 版本
fpdev lazarus default 3.0 # 设置默认 Lazarus 版本
# 交叉编译支持
fpdev cross add win64 # 添加 Windows 64位 交叉编译支持
fpdev cross list # 列出支持的交叉编译目标
# 包管理
fpdev package install <package> # 安装包
fpdev package list # 列出已安装的包
# 项目管理
fpdev project new <name> # 创建新项目
fpdev project build # 构建当前项目FPDev 使用 JSON 格式的配置文件,默认位置:
- Windows:
%APPDATA%\fpdev\config.json - Linux/macOS:
~/.fpdev/config.json
配置文件示例:
{
"version": "1.0",
"default_toolchain": "fpc-3.2.2",
"toolchains": {
"fpc-3.2.2": {
"type": "release",
"version": "3.2.2",
"install_path": "/path/to/fpc/3.2.2",
"source_url": "https://gitlab.com/freepascal.org/fpc/source.git",
"branch": "fixes_3_2",
"installed": true
}
},
"lazarus": {
"default_version": "lazarus-3.0",
"versions": {
"lazarus-3.0": {
"version": "3.0",
"fpc_version": "fpc-3.2.2",
"install_path": "/path/to/lazarus/3.0",
"installed": true
}
}
},
"settings": {
"auto_update": false,
"parallel_jobs": 4,
"keep_sources": true,
"install_root": "/home/user/.fpdev"
}
}- fpdev.config: JSON 配置管理系统
- fpdev.cmd: 命令行处理框架
- fpdev.utils: 跨平台工具函数库
- fpdev.terminal: 终端输出管理
- fpdev.cmd.help: 帮助系统
- fpdev.cmd.version: 版本信息
- fpdev.cmd.fpc: FPC 管理
- fpdev.cmd.lazarus: Lazarus 管理
- fpdev.cmd.package: 包管理
- fpdev.cmd.cross: 交叉编译管理
- fpdev.cmd.project: 项目管理
- 📖 快速开始指南 - 5分钟上手指南
- 🔧 安装指南 - 详细安装说明
- 📋 API 文档 - 完整的API参考
- 🏗️ 架构文档 - 系统架构设计
- 🔧 FPC 管理文档 - FPC管理详解
- 📊 项目总结 - 开发历程总结
- 📄 最终报告 - 项目完成报告
- 📝 发布说明 - v1.0.0 发布说明
项目采用测试驱动开发,包含完整的测试套件:
# 运行所有测试 (Windows)
scripts\run_all_tests.bat
# 运行所有测试 (Linux/macOS)
./scripts/run_all_tests.sh
# 运行单个测试模块
cd src
fpc -Fu. ../tests/test_config_management.lpr
../tests/test_config_management| 模块 | 测试数 | 覆盖功能 |
|---|---|---|
| 项目清理 | 3个 | 清理构建产物、错误处理 |
| 项目运行 | 4个 | 运行可执行文件、参数传递、错误处理 |
| 项目测试 | 4个 | 运行测试、处理失败、错误处理 |
| FPC清理 | 3个 | 清理FPC源码构建产物、递归清理 |
| FPC更新 | 3个 | 更新FPC源码、git pull、错误处理 |
| Phase 1 小计 | 17个 | 100%通过率 |
| 模块 | 测试数 | 覆盖功能 |
|---|---|---|
| 作用域安装 | 6个 | 项目/用户作用域、元数据持久化 |
| 二进制安装 | 8个 | HTTP下载、ZIP解压、跨平台URL |
| 验证框架 | 集成 | 版本检查、smoke test (hello.pas) |
| 激活系统 | 6个 | Shell脚本生成、VS Code集成 |
| Phase 2 小计 | 20+个 | 100%通过率 (除网络依赖测试) |
| 模块 | 测试数 | 覆盖功能 |
|---|---|---|
| Bootstrap 下载器 | 7个 | 平台检测、URL生成、下载/解压/验证 |
| Bootstrap 集成 | 7个 | 端到端工作流、路径检测、错误处理 |
| Phase 4.2 小计 | 14个 | 100%通过率 (除网络依赖测试) |
- 测试套件数: 11个
- 总测试数: 44+
- 通过率: 100%
- 测试方法: TDD (Test-Driven Development)
注: 配置管理、Lazarus、交叉编译、包管理等模块的完整测试套件将在后续阶段添加。
我们欢迎各种形式的贡献!
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 开启 Pull Request
- ✅ 遵循 TDD (测试驱动开发) 方法论
- ✅ 使用 FreePascal 3.2.2+ 编译器
- ✅ 保持代码简洁和可维护性
- ✅ 添加适当的注释和文档
- ✅ 确保所有测试通过
如果 FPDev 对您有帮助,请考虑:
- ⭐ 给项目点个 Star
- 🐛 报告 Bug 和问题
- 💡 提出功能建议
- 📢 向朋友推荐
- 🤝 贡献代码
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
- FreePascal 团队 - 提供优秀的编译器
- Lazarus 团队 - 提供强大的 IDE
- Rust 团队 - rustup 工具提供设计灵感
- 社区贡献者 - 所有测试用户和反馈者
- 🌐 官网: https://fpdev.github.io
- 📧 邮箱: support@fpdev.org
- 💬 Discord: https://discord.gg/fpdev
- 🐛 Issues: https://github.com/fpdev/fpdev/issues
- 💡 讨论: https://github.com/fpdev/fpdev/discussions
- 👨💻 fafafaStudio
- 📧 dtamade@gmail.com
- 💬 QQ群: 685403987
- 🆔 QQ: 179033731
FPDev v1.0.0 - 让 FreePascal 开发更简单! 🚀
Made with ❤️ by the FreePascal community