Skip to content

Latest commit

 

History

History
124 lines (82 loc) · 5.97 KB

DOCKER.md

File metadata and controls

124 lines (82 loc) · 5.97 KB
Raw

Open Orbis Toolchain Dockerfile

Synopsis

The Open Orbis team has put together a Dockerfile to make compiling PKGs with the Open Orbis PS4 Toolchain trivial to do. This makes updating the toolchain simple, stops the environment from becoming contaminated (or contaminating another environment), minimizes the troubleshooting needed for issues, enables building with a particular version, etc. This document is aimed at providing an overview of how to use the Dockerfile to make a developer's life easier. There are multiple methods that can be utilized depending on the developer's individual need at any given time.

Methods

The most common use case for each method is as follows:

  • Single Line Build: You are building a PKG file on your local machine.
  • Github Actions: Used to check pull requests, generate releases, etc on Github without needing user interaction.
  • CLI Access: Testing, debugging, etc.

Single Line Build

Windows:

docker run --rm -w /workspace -v "%cd%":/workspace openorbisofficial/toolchain:latest make

Linux/OSX/BSD:

docker run --rm -w /workspace -v "$(pwd)":/workspace openorbisofficial/toolchain:latest make

This one-liner will run the make command from your current working directory as if it were on a machine with the latest Open Orbis Toolchain installed and working as expected. You can use this to launch a custom script as necessary. See the Build Script section for some caveats.

Note: You can use bash -c to make a script a one liner. Example: docker run --rm -w /workspace -v "%cd%":/workspace openorbisofficial/toolchain:latest bash -c "cd hello_world; make; PkgTool.Core pkg_build pkg/pkg.gp4 ."

Github Actions

The following action will use the Open Orbis Toolchain v0.5 to run make in the project's hello_world directory, then use PkgTool.Core pkg_build pkg/pkg.gp4 . to build a PKG file.

- name: Run Open Orbis Toolchain
        uses: OpenOrbis/toolchain-action@main
        with:
          version: v0.5.1
          command: cd hello_world; make; PkgTool.Core pkg_build pkg/pkg.gp4 .

You could also run the Build Script action.sh from the project's root directory with the latest Open Orbis Toolchain release with the following action:

- name: Run Open Orbis Toolchain
        uses: OpenOrbis/toolchain-action@main
        with:
          version: latest
          command: bash action.sh

Note: The provided action uses the root user as it runs on Github’s infrastructure and not your local machine. You do not need to do anything special to use privileged functions.

CLI Access

You can open an interactive shell within the container with the following command:

Windows:

docker run --rm -it -w /workspace --entrypoint=/bin/bash -v "%cd%":/workspace openorbisofficial/toolchain

Linux/OSX/BSD:

docker run --rm -it -w /workspace --entrypoint=/bin/bash -v "$(pwd)":/workspace openorbisofficial/toolchain

Note 1: In the above commands only changes made in the /workspace directory will remain as it is the mounted directory and is actually on the host machine.

Note 2: The default user used is the unprivileged "orbis" user. If you need to use privileged functions add --user root or --user 0 to the command.

Docker Requirement

To use the "CLI Access" and "Single Line Build" method you must have Docker installed locally.

Building Docker Image

When manually building a Docker image based on the Dockerfile you must specify the version of the toolcahin to build for with --build-arg OO_TOOLCHAIN_VERSION= ex. docker build -t "ootoolchain:v0.5.1" . --build-arg OO_TOOLCHAIN_VERSION=v0.5.1

Build Script

Some notes to keep in mind:

  • This is a minimal Ubuntu 20.04 installation. You'll need to install other applications as necessary
  • The default user used is the unprivileged "orbis" user. If you need to use privileged functions add --user root or --user 0 to the command
  • The working directory will be the repo's root directory
  • Use relative paths for locations within the repo's directory
  • ANY error should stop the Github Action immediately

Other Tips

  • It is possible to specify why Toolchain version to use by specifying the version in the commands. ex. openorbis/toolchain:v0.5.1, you can also use latest to use the most recent build.
  • docker pull openorbis/toolchain will update your Docker container to the latest release or docker pull openorbis/toolchain:v0.5.1 to pull a specific version's update.
  • Always pull the new container's data before deleting old containers as there may be overlap/cached data and will save you download time

Docker Development

The development of the Dockerfile and this document file can be found here. This repo uses Github Actions to build and publish the Docker container to Docker Hub automatically on releases. The workflow file can be found here. The Github Action for the toolchain can be found here.

Additional Support

Additional support will be provided in the Open Orbis Discord server.