Skip to content

Continuous Integration

Jump to bottom Edit New page
Jack Greiner edited this page Dec 4, 2021 · 1 revision

Continuous Integration

Workflow and runners

CI is handled in a single workflow located at .github/workflows/naev_ci.yml and is triggered when a pull request is submitted, or a push has been made the the naev/naev repository.

You can view the status of any CI runs in the 'Actions' tab on the main repository page.
You can also click here: CI

This workflow starts 5 'jobs' per run:

These jobs will attempt to compile Naev.

Build Environments

All build environments are built in the form of Docker containers. These containers are used for all jobs in our CI and CD workflows, from test builds to documentation generation.

Our current Infrastructure dockerfiles and sources are located here. Further details about each image will be documented on the wiki here

All platforms that are not native Linux, are cross compiled using these configured environments, with assistance of the Meson cross-files located here. These ini files define which tools should be used when test-building Naev, in the case of Windows builds, build tool wrappers for the MinGW toolchain are referenced in windows_cross_mingw.ini.

Workflow Jobs

Package_Source

This job is responsible for testing if the Naev dist can be properly generated from the source tree. If this job fails to run, none of the below jobs will start and the CI run will be considered a failure.

There are 3 steps for this job

  • "Checkout Naev Repository"
    • Checks out the naev/naev repository to the work folder under the sub-directory of 'source'. This also includes any git submodules as well.
  • "Package Dist"
    • Runs meson setup and meson dist, outputting a tar.xz archive and SHA256 Checksum.
  • "Upload Dist Artifact"
    • Uploads the outputs of the prior step (e.g. naev-..*.tar.xz) for use with the later jobs, as they make use of the Naev dist for builds.
    • This artefact is named naev-dist-GITSHA

Linux_Compile_Naev

This job is responsible for test building Naev in our 3 Linux build environments, and is directly dependant on the Package_Source job.

These environments are:

  • naev-linux-latest
    • This image is based on Fedora Rawhide, and features very close to upstream versions of dependencies such as SDL, and utilities such as Meson.
  • naev-linux-lts
    • This image is based on CentOS 7, and is used for building Linux releases outside of Steam. It has back-ported versions of utilities such as Meson preinstalled and provides a long lasting release target.
  • naev-steamruntime
    • This image is based on Steam Runtime 2: Soldier, and is used for building Linux releases for Steam. It has back-ported versions of utilities such as Meson preinstalled and provides a supported and stable Steam Linux release target.

Test-build steps

These steps are more-or-less copy paste for all platforms we test for, however each platform has it's share of special options that need to be passed into Meson to succeed in building.

  • Get Source
    • Downloads the naev-dist-GITSHA artefact from the Package_Source job for use in later steps.
  • Extract Source
    • Extracts naev-*.*.*.tar.xz to the working directory, under the sub-directory of 'source'.
  • Meson Setup
    • Runs meson setup configuring a meson build into the sub-directory of 'build'.
  • Upload Setup Log
    • Regardless of the success of the 'Meson Setup' step, a setup log will be uploaded to help debug potential build issues.
    • This artefact is named imagename-GITSHA-setup-log
  • Meson Compile
    • Runs meson compile in the 'build' sub-directory, test-building Naev.
  • Upload Compile Log
    • Regardless of the success of the 'Meson Compile' step, a compile log will be uploaded to help debug potential compilation errors or warnings.
    • This artefact is named imagename-GITSHA-compile-log
  • Upload Build Artifacts
    • The contents of the 'build' directory are compressed and uploaded for developers to download and further test on their own machines.
    • This artefact is named imagename-GITSHA-buildArtifacts
  • Test Install
    • This step will run meson install testing the installation steps defined in the project meson.build.
  • Upload Install Log
    • Regardless of the success of the 'Test Install' step, an install log will be uploaded to help debug potential installation errors.
    • This artefact is named imagename-GITSHA-install-log

Linux-specific steps

These steps are only run for the Linux_Compile_Naev job.

  • Compile AppImage
  • Upload AppImage Compile Log
    • Regardless of the success of the 'Compile AppImage' step, an AppImage compile log will be uploaded to help debug potential compilation errors or warnings.
    • This artefact is named imagename-GITSHA-AppImageBuild-log

Windows_Compile_Naev

This job is responsible for test building Naev in our Windows build environment, and is directly dependant on the Package_Source job.

This environment is:

Build steps are outlined here: Test-build steps

Windows-specific notes

Windows builds make use of the cross-file in utils/build/windows_cross_mingw.ini as this defines which tool wrappers should be used.

Darwin_Compile_Naev

This job is responsible for test building Naev in our Darwin/macOS build environment, and is directly dependant on the Package_Source job.

This environment is:

Build steps are outlined here: Test-build steps

macOS-specific notes

macOS builds make use of the cross-file in utils/build/macos_cross_osxcross.ini as this defines which tool wrappers should be used.

Lua_Lint

This job is responsible for running luacheck using our naev-linux-latest build environment, and is directly dependant on all previously mentioned jobs.

The definition file that houses all rules that luacheck follows is located in .luacheckrc

Job steps

  • Get Source
    • Downloads the naev-dist-GITSHA artefact from the Package_Source job for use in later steps.
  • Extract Source
    • Extracts naev-*.*.*.tar.xz to the working directory, under the sub-directory of 'source'.
  • Meson Setup
    • Runs meson setup configuring a meson build into the sub-directory of 'build'.
  • Meson Test
    • Runs meson compile in the 'build' sub-directory, test-building Naev.
  • Upload Test Log
    • Regardless of the success of the 'Meson Test' step, a test log will be uploaded to help clean up any code issues.
    • This artefact is named GITSHA-lualint-testlog

Lua_Documentation

This job is responsible for test building Naev documentaiton using our naev-docs environment, and is directly dependant on Lua_Lint.

Job steps

  • Get Source
    • Downloads the naev-dist-GITSHA artefact from the Package_Source job for use in later steps.
  • Extract Source
    • Extracts naev-*.*.*.tar.xz to the working directory, under the sub-directory of 'source'.
  • Meson Setup
    • Runs meson setup configuring a meson build into the sub-directory of 'build', and disabling the naev executable from being built.
  • Meson Compile
    • Runs meson compile in the 'build' sub-directory, test-building Naev Documentation.
  • Upload Compile Log
    • If the 'Meson Compile' step fails, a build log will be uploaded to help diagnose issues.
    • This artefact is named GITSHA-ldoc-log
  • Trigger API Documentation Update
    • This step is triggered by a push trigger and will not run on a fork. It sends a repository_dispatch trigger to the naev/naev.github.io repository to start the deployment of the API documentation, ensuring it remains synced with development.

View the deployment status here: Build and Publish Website
If it is successful; the updated documentation is visible here: Naev Lua API.

Build Artefacts and Build Health

Build artefacts and any errors are available after workflow completion in the run overview (for up to 30 days). An example can be found here

CI build health is visible in the header of Readme.md or right here:
CI

Add a custom footer

Home

Lore

Lore is being removed from the Wiki and moved into docs/manual/lore/.

Manual

Development

Clone this wiki locally