Skip to content

dtamade/fpdev

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

182 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

FPDev - FreePascal Development Environment Manager

FPDev Git2 – Usage and Build Guide

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 impl src/git2.impl.pas
  • C API bindings (libgit2): src/libgit2.pas

Notes:

  • fpdev.git2 exposes concrete classes (TGitManager/TGitRepository/...) and keeps a compatibility shim TGit2Manager.
  • New code should prefer git2.api + git2.impl (interfaces first, easy to replace backends). Existing code can continue to use fpdev.git2 safely.
  • fpdev.git (system git command wrapper) is deprecated; libgit2 path is the preferred backend.

Quick Start

  • Recommended imports in applications/tests:

    • Preferred: uses git2.api, git2.impl; then NewGitManager() to obtain IGitManager
    • Compatible: uses fpdev.git2; then GitManager singleton or TGitManager.Create
    • Only import libgit2 when you must call the C API directly
  • Build (Lazarus is on PATH):

    • lazbuild --build-all --no-write-project test_libgit2_simple.lpi
    • lazbuild --build-all --no-write-project test_libgit2_complete.lpi
    • lazbuild --build-all --no-write-project tests\test_git2_adapter.lpi
    • lazbuild --build-all --no-write-project tests\test_ssl_toggle.lpi
    • lazbuild --build-all --no-write-project tests\test_offline_repo.lpi
  • Runtime requirement (Windows): Ensure git2.dll is discoverable (next to the executable or in PATH).


Usage cheatsheet

# 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 tests

High‑level API (fpdev.git2)

Exposes 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 checks
  • TGitCommit, TGitReference, TGitRemote, TGitSignature and EGitError

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.


C API (libgit2)

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.

Migration Notes

  • Replace any uses git2.modern with uses fpdev.git2.
  • Replace any uses libgit2_netstructs or libgit2.dynamic with nothing (types/options are unified in libgit2.pas).
  • Where old code passed libgit2.dynamic.git_branch_t(...), use plain GIT_BRANCH_LOCAL/REMOTE/ALL directly.

Testing

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.


Support Matrix & Notes

  • Windows: looks for git2.dll
  • Linux/macOS: ensure appropriate libgit2 shared library is available (see constants in libgit2.pas for default names)
  • Compilers: tested with recent FPC trunk; adjust as needed.

Contact / Contributing

  • Open issues for missing libgit2 API you need. Prefer adding to fpdev.git2 first; expose C API only when necessary.
  • Keep the one‑unit‑per‑layer rule: high‑level in fpdev.git2, C API in libgit2.

FPDev Logo

现代化的 FreePascal 和 Lazarus 开发环境管理工具

Release License Tests Platform

快速开始安装指南文档贡献

🎯 项目简介

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

🛠️ 功能模块

1. FPC 版本管理

# 二进制安装(默认,快速)
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

激活系统(Phase 2.4)

激活后会生成 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 中的路径配置

FPC 源码管理详解

清理源码构建产物 (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

Bootstrap 编译器自动管理(Phase 4.2)✅

从源码构建 FPC 时,FPDev 会自动下载并管理所需的 bootstrap 编译器:

自动化流程

  1. 检测目标 FPC 版本所需的 bootstrap 版本(例如 FPC 3.2.2 需要 3.0.4)
  2. 优先使用系统已安装的 FPC(如果版本兼容)
  3. 如无兼容版本,自动从 SourceForge 下载对应平台的 bootstrap 编译器
  4. 下载后自动解压到 sources/fpc/bootstrap/fpc-<version>/ 目录
  5. 验证 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(编译器路径、库路径等)

Lazarus IDE 配置(Phase 3.4)✅

fpdev lazarus configure 命令自动配置 Lazarus IDE 的编译器和库路径:

自动化配置

  1. 检测已安装的 Lazarus 版本
  2. 查找对应的 FPC 编译器路径
  3. 自动配置 environmentoptions.xml 文件
  4. 设置编译器路径、库路径、FPC 源码路径
  5. 创建配置备份(带时间戳)

配置内容

  • 编译器路径(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.2

3. 交叉编译支持

fpdev cross list --all                    # 列出支持的平台
fpdev cross install win64                 # 安装交叉编译目标
fpdev cross configure win64 --binutils=/path --libraries=/path

4. 包管理

fpdev package install synapse             # 安装包
fpdev package list --all                  # 列出包
fpdev package repo add custom https://example.com/repo

5. 项目管理

fpdev 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)

6. 统一配置

  • 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"
  }
}

🏗️ 架构设计

核心模块

  1. fpdev.config: JSON 配置管理系统
  2. fpdev.cmd: 命令行处理框架
  3. fpdev.utils: 跨平台工具函数库
  4. 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: 项目管理

📚 文档

🧪 测试

项目采用测试驱动开发,包含完整的测试套件:

# 运行所有测试 (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

测试覆盖 (Phase 1 & Phase 2 - TDD)

Phase 1: Core Workflow

模块 测试数 覆盖功能
项目清理 3个 清理构建产物、错误处理
项目运行 4个 运行可执行文件、参数传递、错误处理
项目测试 4个 运行测试、处理失败、错误处理
FPC清理 3个 清理FPC源码构建产物、递归清理
FPC更新 3个 更新FPC源码、git pull、错误处理
Phase 1 小计 17个 100%通过率

Phase 2: Installation Flexibility ✅ COMPLETE

模块 测试数 覆盖功能
作用域安装 6个 项目/用户作用域、元数据持久化
二进制安装 8个 HTTP下载、ZIP解压、跨平台URL
验证框架 集成 版本检查、smoke test (hello.pas)
激活系统 6个 Shell脚本生成、VS Code集成
Phase 2 小计 20+个 100%通过率 (除网络依赖测试)

Phase 4: Polish and Optimization ✅ PARTIAL

模块 测试数 覆盖功能
Bootstrap 下载器 7个 平台检测、URL生成、下载/解压/验证
Bootstrap 集成 7个 端到端工作流、路径检测、错误处理
Phase 4.2 小计 14个 100%通过率 (除网络依赖测试)

总计

  • 测试套件数: 11个
  • 总测试数: 44+
  • 通过率: 100%
  • 测试方法: TDD (Test-Driven Development)

: 配置管理、Lazarus、交叉编译、包管理等模块的完整测试套件将在后续阶段添加。

🤝 贡献

我们欢迎各种形式的贡献!

如何贡献

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 开启 Pull Request

开发规范

  • ✅ 遵循 TDD (测试驱动开发) 方法论
  • ✅ 使用 FreePascal 3.2.2+ 编译器
  • ✅ 保持代码简洁和可维护性
  • ✅ 添加适当的注释和文档
  • ✅ 确保所有测试通过

贡献类型

  • 🐛 Bug 报告: 提交 Issue
  • 💡 功能建议: 功能讨论
  • 📝 文档改进: 直接提交 PR
  • 🔧 代码贡献: 遵循上述流程

🌟 支持项目

如果 FPDev 对您有帮助,请考虑:

  • ⭐ 给项目点个 Star
  • 🐛 报告 Bug 和问题
  • 💡 提出功能建议
  • 📢 向朋友推荐
  • 🤝 贡献代码

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

  • FreePascal 团队 - 提供优秀的编译器
  • Lazarus 团队 - 提供强大的 IDE
  • Rust 团队 - rustup 工具提供设计灵感
  • 社区贡献者 - 所有测试用户和反馈者

📞 联系方式

原作者

  • 👨‍💻 fafafaStudio
  • 📧 dtamade@gmail.com
  • 💬 QQ群: 685403987
  • 🆔 QQ: 179033731

FPDev v1.0.0 - 让 FreePascal 开发更简单! 🚀

Made with ❤️ by the FreePascal community

About

freePascal 工具箱

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors