How ungoogled-software/ungoogled-chromium-windows works
Project Type and Purpose
• This project is a specialized build and packaging system for ungoogled-chromium on Windows. Its main purpose is to automate source code retrieval, patch application, compilation, and package creation (installer and zip archive) while also integrating with CI tools.
• The README emphasizes detailed build instructions, external environment setup (Visual Studio, Python, MSYS2), patch management, and dependency updates – highlighting that it is as much a build orchestration system as it is a packaging system.
Analyzing the File Structure
• Top-Level Directories & Files:
• .github: Contains GitHub Actions for CI/CD, which includes custom actions for staging builds and integration with winget (for installing the packaged app).
• devutils: Scripts for patch checking, tag version printing, and environment variable setup. These support developer workflows and patch consistency.
• patches: Contains a deep hierarchy of patches (organized by series and platform: Windows-specific patches for Chromium) used during the build process.
• build.py and package.py: Core Python scripts used to drive the build and packaging operations.
• downloads.ini and revision.txt: Configuration files for managing external downloads and source revision tracking.
• flags.windows.gn: A configuration file that affects build settings like target architecture.
• ungoogled-chromium: Likely a submodule containing the upstream source, representing the core Chromium codebase.
• The file tree shows a clear separation between CI/CD configuration (.github), build automation (Python scripts, configuration files), patch management, and developer utilities.
Architectural Components
A. External Environment & Dependencies
• Visual Studio and Windows SDK: Needed for the compilation process.
• Python (3.8+): The interpreter for running build.py, package.py, and other scripts.
• MSYS2 and associated tools (quilt, dos2unix): Utilized specifically for patch management and developer setup.
• Git: For source retrieval (cloning repositories and updating submodules).
• External packages: 7-Zip, NodeJS, ninja, etc. (as mentioned in the README) are integrated into the process.
B. Source & Download Management
• downloads.ini defines external source URLs and checksums.
• The ungoogled-chromium submodule (and related utilities in ungoogled-chromium/utils) that manage cloning and fetching the Chromium code.
C. Patch Management
• The patches folder, containing both a “series” file and platform-specific patch scripts, outlines the modifications to be applied to Chromium.
• Developer utilities (in devutils) for checking and updating patches.
D. Build and Packaging Pipeline
• build.py: Orchestrates the overall build process from downloading and applying patches to initiating a Windows build.
• package.py: Creates deliverables (zip archive and installer) from the built binaries.
E. CI/CD Integration
• GitHub Actions workflows (.github/workflows/main.yml) and custom actions (.github/actions/stage and winget) used for automating builds and package distribution.
Relationships and Data Flow
• A sequential workflow:
1. Developer or CI trigger initiates the Process.
2. Source Code Retrieval: Git fetches the Chromium source (managed via downloads.ini and ungoogled-chromium submodule).
3. Patch Management: The build scripts call patch utilities (via Python scripts and devutils) to apply the patches from the patches directory.
4. Build Process: build.py invokes the compiler using Visual Studio and MSYS2 tools. Configurations like flags.windows.gn affect the build.
5. Packaging: package.py wraps up the build outputs into a zip archive and an installer.
6. CI/CD Actions: GitHub Actions (and specifically the actions defined under .github) monitor the process and, if required, publish the package (including winget integration for easy installation).
Architectural Patterns and Design Principles
• Modularity and separation of concerns: The build process is decomposed into distinct modules (source retrieval, patch application, compilation, packaging, deployment).
• Integration with CI/CD pipelines, showing how automated scripts and developer utilities fit into the system.
• Point out any “customized” automation: The project has its own build flow that intentionally avoids using tools like depot_tools, which signifies a custom orchestration layer.