Packaging tutorial - dreamer/luxtorpeda GitHub Wiki

Quick overview

Luxtorpeda packages are Git repositories with specific file structure, using GitLab CI to rebuild and publish the packages. They are all stored in luxtorpeda/packages sub-group on GitLab.

Creating your first package

Local Git configuration

All the usual steps involved with settiing up Git are required: uploading you ssh keys to GitLab and configuring your name and email:

$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"

Local Docker configuration

TODO Create separate page describing initial Docker setup; until then following steps can be used (Fedora only): https://github.com/ValveSoftware/Proton/wiki/Build-instructions-(Fedora)#install-docker

Bootstrapping a package repo

Prepare the package name. It should be the name of a game engine you are packaging, all lowercase, using minus characters (-) in place of underscores or whitespace. For example, let's pretend we are packaging an engine called "OpenGame_x" - package name in Luxtorpeda therefore should be: opengame-x. In most cases, the package name should reflect the name of engine repository.
Clone package-template repository from GitLab with few convenience options, using our selected name:
```
$ git clone [email protected]:luxtorpeda/packages/template.git -o template opengame-x
```
This will clone the template repository, name remote template (instead of default origin - this will be useful later) and name the local directory opengame-x.
Run bootstrap script inside the newly cloned repo:
```
$ cd opengame-x
$ ./bootstrap/update
```
The script will ask you to confirm the package name and ask for Steam AppIds this game will be used for. AppIds should be a list of space-separated numbers, e.g. 12340 56780. Bootstrap script will create several files:
- .gitlab-ci.yml - CI configuration, that will automatically build and publish your package using GitLab CI
- env.sh - environment variables, that are sourced in relevant shell scripts
- index.html - html template page for this package; it will be automatically deployed with your package (for human consumption)
- manifests/* - json template files describing how to run this game
Commit these files:
```
$ git add .gitlab-ci.yml env.sh index.html manifests
$ git commit -m "Bootstrap the package"
```
Run ./lint.sh to verify if your package is in good state so far:
```
$ ./lint.sh 
+ shellcheck ./build.sh ./env.sh ./lib.sh ./lint.sh ./package.sh ./run-build.sh
+ pylint bootstrap/start.py

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)
```
Packages not getting the perfect score are not going to be accepted.
Add source code of game engine as Git submodule named source.

If source code of an engine is already included in luxtorpeda/mirrors/ then use relative address ../../mirrors/<project-name>.git:
```
$ git submodule add ../../mirrors/opengame-x.git source
```
Otherwise, send a request for mirroring to the Luxtorpeda maintainers, but in the meantime you can start work using absolute url:
```
$ git submodule add <project-url> source
```
Then, commit new submodule:
```
$ git commit -m "Add source submodule"
```
Relative submodule urls are preferred over absolute ones for multiple reasons:
- Makes project more independent from specific hosting provider
- Provides backup of upstream repo
- Faster CI builds
- We can use it for patch management (in case we need to modify sources a bit to make them work with Steam)
Provide build instructions in file build.sh - this script will be used by CI to build our package. You can test build process on your computer with script run-build.sh.

TODO: describe where to put resulting files; TODO article about setting up Docker; TODO: make adnotation about dependencies not included in docker image
Once you can easily rebuild the package, we need to include information describing how to run it. Edit relevant json file in manifests/ directory. You need to update these lines:
```
"commands": [
        {
                "match_cmd": ".*",
                "cmd": "",
                "args": []
        }
]
```
match_cmd: this field contains regular expression (Rust syntax), which will be matched against original command invoked by Steam when running the game. Some titles include more than one programs (e.g. main game and settings application) - this regex is used to select the proper command to replace the original one. If game does not use Steam launcher UI, then you can leave value .* in here.

cmd: either name of the binary we just compiled or launcher script that was included in the package. Example:
```
"cmd": "./opengame.sh",
```
args: table of additional parameters - sometimes it's easier to inject them here instead of writing launcher script. Example:
```
"args": ["-foo", "bar baz"]
```
Remember, Steam might append additional arguments when launching the game! They will be appended after args defined in this file.

Once done, commit updated manifest file to repo; after successfull build it will be automatically filled with build information and placed inside package file in proper location.
TODO: invoke package.sh locally, place tarballs in cache, edit packages.json to sideload your package for testing purpose
TODO: describe; create repo on GitLab, set it as origin and push
TODO: push to GitLab to test if it builds on CI (time and disk quotas and artifact handling cannot be 100% tested locally)
TODO: describe the workflow for submissions