Principia Documentation

To add a new external dependency (e.g., a GitHub repository) to the Principia ecosystem, follow these steps to set up the directory structure, MSVC solution, and CI/CD pipelines.

1. Directory and Repository Setup

1. Decide on an organization name (e.g., Bar) and a component name (e.g., foo).
2. Create the directory Principia\Bar.
3. Inside Principia\Bar, clone the repository:

   git clone https://github.com/Bar/foo.git

4. Create an MSVC directory: cd Principia\Bar\foo && mkdir msvc.
5. Create a solution file at msvc\foo.sln.
6. Copy common.props into msvc\foo.props.

2. MSVC Project Configuration

1. Create an Empty Project C++ named foo inside foo\msvc. This results in the structure foo\msvc\foo\... to prevent name clashes.
2. (Optional) If the component has benchmarks, create an Empty Project C++ named benchmarks in foo\msvc.
3. (Optional) If the component has tests, create an Empty Project C++ named tests in foo\msvc.
4. Unload all projects in the solution and edit their .vcxproj files to include the following import (preserving existing GUIDs):

   <?xml version="1.0" encoding="utf-8"?>
   <Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
     <PropertyGroup Label="Globals">
       <VCProjectVersion>17.0</VCProjectVersion>
       <ProjectGuid>{...}</ProjectGuid>
     </PropertyGroup>
     <Import Project="$(SolutionDir)foo.props" />
     <ItemGroup></ItemGroup>
   </Project>

5. Edit msvc\foo.props:
   • Replace the-include-directory with the directory containing headers.
   • Replace the-benchmark-project with the benchmark project name (use xxx if none).
   • Replace the-test-project with the test project name (use xxx if none).
   • Remove imports under condition PrincipiaBenchmarkProject if not using Google\benchmark.
   • Remove imports under condition PrincipiaTestProject if not using Google\googletest.
6. Load All Projects and add header/source files via Add > Existing Item....

3. Compilation and Linking

• Ensure the project compiles. You can use the PRINCIPIA symbol to condition code changes if necessary.
• Ensure the project links. Add dependencies in the tests and benchmarks projects to link against the foo library.

4. Solution Filtering

1. Save the solution as a Solution Filter: Save As Solution Filter named msvc\foo.slnf.
2. Add msvc\foo.slnf to Solution Items via Add > Existing Item....
3. Edit msvc\foo.slnf to remove non-production projects (benchmarks, tests, etc.).

5. CI/CD Pipeline Setup (GitHub Actions & DevOps)

1. Create .github\workflows\build.yaml in the component directory. Adapt it from an existing project (e.g., Google\re2).
2. Update env variables and the artifact name to foo.
3. Add a step to download the artifact in build.yaml:

    - name: Download foo artifact
      uses: mockingbirdnest/actions/windows/download_artifact@main
      with:
        name: foo
        configuration: ${{ matrix.configuration }}
        directory: Bar

4. In Azure DevOps, add PRINCIPIA_HEADERS_FOO and PRINCIPIA_MSVC_FOO to the Principia variable group.
5. Clone existing pipelines for Windows, Ubuntu, and macOS. Update the Get sources step (repo/branch) and Publish Build Artifacts step (CopyArtifactsContents and PublishArtifactName).
6. For Ubuntu and macOS, create foo\principia_make.sh and foo\principia_variable_overrides.sh to handle builds.
7. Add a step in the Ubuntu and macOS pipelines to download the foo artifact.

Building Principia on Linux is a best-effort process.

Prerequisites:

1. Clone the repository:

   git clone https://github.com/mockingbirdnest/Principia.git
   cd Principia

2. Install plugin build prerequisites: unzip, wget, binutils, make, automake, libtool, curl, and cmake.
3. Install adapter build prerequisites: msbuild.
4. Install Clang version 20 using the following commands:

   wget https://apt.llvm.org/llvm.sh
   chmod +x llvm.sh
   sudo ./llvm.sh 20 all
   sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-20 200
   sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-20 200

Build Steps:

1. Install and compile third-party dependencies:

   ./install_deps.sh

   Do not proceed if this step encounters errors.
2. Link KSP and Unity assemblies. Principia expects these in a directory adjacent to the Principia directory (e.g., ../KSP Assemblies/1.12.5).
3. Run the build:

   make

   Note: If unit tests fail, the resulting binary may not be functional.

Principia includes a journaling mechanism to record interactions between KSP and Principia to help analyze complex bugs. If requested by developers, follow these steps:

1. Open Logging Settings in the main Principia window.
2. Select Record journal (starts on load) at the bottom left.
3. Perform a scene change to ensure journaling is active (verify Journaling is ON appears at the bottom right of the Principia window).
4. Reproduce the problem (note: journaling may slow down the game).
5. If successful, send the relevant *.log files and the JOURNAL.* file found in your glog\Principia directory.

CRITICAL: Deselect Record journal (starts on load) when finished, otherwise your game will remain slow.

Steps to enable journaling:
1. Open 'Logging Settings'
2. Select 'Record journal (starts on load)'
3. Change scenes to verify 'Journaling is ON'
4. Reproduce issue
5. Submit *.log and JOURNAL.* files from glog\Principia

To build Principia on Windows, ensure you have the following prerequisites installed:

• Visual Studio 2022 (version 17.14.23 or later) with C# and C++ support. Note: Visual Studio 2026 is not supported.
• Windows SDK 10.0.22621 (newer SDKs are not supported).
• .NET Framework 4.7.2 SDK (including the Targeting Pack).

Note on Visual Studio Editions: The solution includes a C# project named coverage_analyser which requires the Enterprise edition. If you are using a different edition, you can still build and test the mod by right-clicking the project and selecting Project > Unload Project.

Setup Steps:

1. Create a <root> directory. Ensure it does not contain subfolders named Principia, KSP Assemblies, or Google.
2. Clone the repository into <root> using Git PowerShell:

   git clone https://github.com/mockingbirdnest/Principia.git

3. Copy KSP 1.12.5 assemblies to <root>\KSP Assemblies\1.12.5.
4. Run the rebuild script from <root>:

   .\Principia\rebuild_all_solutions.ps1

Troubleshooting: If the build fails with error C1060, the machine may be running out of resources. Try:

• Reducing parallelism by changing the /m flag in the msbuild command within the script (e.g., to /m:1 or /m:2).
• Increasing the size of the Windows paging file.

When the upstream dependency (e.g., google/master) has moved forward, use the following workflow to rebase your local changes on top of the latest upstream state. This process involves tagging the current state, resetting master to the previous baseline, pulling the new upstream changes, and rebasing your work via a temporary Ketchup branch.

Workflow Steps

1. Tag the current state: Create a tag for your current master so you can return to it if needed.
2. Create a catch-up branch: Create a new branch named Ketchup from master.
3. Reset master to the previous baseline: Move your local master back to the commit where the last catch-up was applied (typically the commit matching google/master).
4. Pull upstream changes: Pull the latest changes from the upstream source (e.g., google/master) into your local master.
5. Rebase changes: Rebase your Ketchup branch onto the updated master.
6. Verify and Fix: Ensure the project compiles and tests pass. You may need to:
   • Update props files to use the correct language dialect.
   • Add or remove projects (use a GUID generator for new projects).
   • Update project contents (use build_projects_helper.ps1 if available to regenerate Visual Studio XML).
7. Update master: Merge Ketchup back into master and force push.
8. Cleanup: Optionally squash commits on master using interactive rebase, but keep the Ketchup branch intact for future reference.

# 1. Tag current master
git checkout master
git tag master20210521

# 2. Create Ketchup branch
git checkout master
git checkout -b Ketchup

# 3. Reset master to previous baseline
git checkout master
git log --oneline
git reset --hard <commit>

# 4. Pull upstream
git pull google master

# 5. Rebase work
git checkout Ketchup
git rebase master

# 6. Update master
git checkout master
git merge Ketchup
git push -f

# 7. Optional: Squash commits on master
git rebase -i <commit>