Services like Travis CI and AppVeyor allow us
to apply continuous integration practices to Common Lisp software across 3 major platforms:
Windows (AppVeyor), GNU/Linux and macOS (Travis CI). Not only pure CI, but it is also
possible to deploy built software to several providers including GitHub
releases. trivial-gamekit is shaped with CI and cross-platform building in
mind. Unfortunately, I’m not going to explain how to use those services in great detail, but
only the bits required to build software based on trivial-gamekit.
Lets see what has to be done to use those tools with GitHub.
If you don’t have Travis CI account yet, go to its website and follow registration process. Setup Travis CI to track your project’s GitHub repository.
Put this snippet into .travis.yml at the root directory of your project:
language: common-lisp
sudo: false
addons:
apt:
packages:
- zip
env:
global:
- GAMEKIT_SYSTEM_NAME: example
- GAMEKIT_APPLICATION_PACKAGE: example-package
- GAMEKIT_APPLICATION_MAIN_CLASS: example
- PATH: ~/.bodge/bin/:$PATH
- GAMEKIT_TARGET_PACKAGE: $GAMEKIT_SYSTEM_NAME-x86-64-$TRAVIS_OS_NAME-$TRAVIS_BRANCH.zip
- GAMEKIT_BUILD_DIR: /tmp/$GAMEKIT_SYSTEM_NAME
- secure: "your+encrypted+data+containing+GITHUB_TOKEN=githubaccesstoken"
branches:
only:
- "/^v\\d+(\\.\\d+)+$/"
os:
- linux
- osx
install:
- curl -L http://bodge.borodust.org/files/install.sh | sh
- lisp install-dist
script:
- >
lisp build-gamekit-system
$GAMEKIT_SYSTEM_NAME $GAMEKIT_APPLICATION_PACKAGE $GAMEKIT_APPLICATION_MAIN_CLASS
$TRAVIS_BUILD_DIR
$GAMEKIT_BUILD_DIR
before_deploy:
- mv "$GAMEKIT_BUILD_DIR/$GAMEKIT_SYSTEM_NAME.zip" $GAMEKIT_TARGET_PACKAGE
deploy:
provider: releases
api-key: $GITHUB_TOKEN
file: $GAMEKIT_TARGET_PACKAGE
skip_cleanup: true
overwrite: true
on:
tags: true
First, you need to generate private GitHub access token, encrypt it and let travis know about it, so it could deploy prepared packages to your repository. Here’s the guide explaining how to encrypt your token. Encryption command would look something like this:
travis encrypt GITHUB_TOKEN="yourgeneratedgithubtoken"
Put encrypted string into env.global section of .travis.yml (See secure value above).
Replace example value in GAMEKIT_SYSTEM_NAME with actual name of asdf system of your
project. Put package name that contains your main class (defined with gamekit:defgame) into
GAMEKIT_APPLICATION_PACKAGE and name of this class into GAMEKIT_APPLICATION_MAIN_CLASS
variable. That should be enough to build the project!
This .travis.yml is setup to build a project on tag push. Tag name should use v +
version-triplet format, e.g.v1.0.0.
Commit changes and push to your repo:
git add .
git commit -m "Travis CI configuration"
git tag v1.0.0
git push origin v1.0.0
Travis CI should pick up the changes, start to build your project and then deploy resulting package
into GitHub releases of your project repository under v1.0.0 tag.
While Travis CI allows you to build GNU/Linux and macOS version of your software, it
doesn’t support Windows yet. Hopefully, AppVeyor does!
Go to AppVeyor website and follow their registration process that is straightforward as Travis CI one. Setup AppVeyor to track your project’s GitHub repository in similar to Travis CI manner.
Put this snippet into .appveyor.yml at the root directory of your project:
image:
- Visual Studio 2017
platform:
- x64
environment:
global:
GAMEKIT_SYSTEM_NAME: example
GAMEKIT_APPLICATION_PACKAGE: example-package
GAMEKIT_APPLICATION_MAIN_CLASS: example
GAMEKIT_ARTIFACT: $(GAMEKIT_SYSTEM_NAME)-x86-64-windows-$(APPVEYOR_REPO_TAG_NAME).zip
GAMEKIT_BUILD_DIR: $(TMP)\$(GAMEKIT_SYSTEM_NAME)
skip_non_tags: true
branches:
only:
- master
- "/^v\\d+(\\.\\d+)+$/"
install:
- set PATH=C:\msys64\usr\bin\;%PATH%
- pacman --noconfirm -Syu
- pacman --noconfirm -S zip
- sh -c "curl -L http://bodge.borodust.org/files/install.sh | sh"
- sh -c "$HOME/.bodge/bin/lisp install-dist"
build_script:
- >
sh -c "$HOME/.bodge/bin/lisp build-gamekit-system
%GAMEKIT_SYSTEM_NAME% %GAMEKIT_APPLICATION_PACKAGE% %GAMEKIT_APPLICATION_MAIN_CLASS%
$(cygpath -u '%APPVEYOR_BUILD_FOLDER%')
$(cygpath -u '%GAMEKIT_BUILD_DIR%')"
- mv %GAMEKIT_BUILD_DIR%\%GAMEKIT_SYSTEM_NAME%.zip %GAMEKIT_ARTIFACT%
artifacts:
- path: "%GAMEKIT_ARTIFACT%"
name: release_archive
deploy:
provider: GitHub
release: $(APPVEYOR_REPO_TAG_NAME)
tag: $(APPVEYOR_REPO_TAG_NAME)
description: $(APPVEYOR_REPO_COMMIT_MESSAGE)
auth_token:
secure: "yourencryptedgithubkey"
artifact: release_archive
force_update: true
draft: false
prerelease: false
on:
appveyor_repo_tag: true
Just like with Travis CI, you would need to generate private GitHub access
token, encrypt it via AppVeyor encryption
page putting there your new access token and replace
secure value of deploy section of the snippet above with an actual value. Same as with
.tavis.yml, put package name that contains your main class (defined with gamekit:defgame)
into GAMEKIT_APPLICATION_PACKAGE and name of this class into GAMEKIT_APPLICATION_MAIN_CLASS
variable. Again, just like Travis CI config, this .appveyor.yml is setup to build a project
on tag push. Tag name should use v + version-triplet format, e.g.v1.0.0.
Commit changes and push new tag to project origin:
git add .
git commit -m "AppVeyor CI configuration"
git tag v1.0.1
git push origin v1.0.1
Binary package for Windows with v1.0.1 version of your project should be deployed to its
GitHub repository after successful build!
cl-bodgetrivial-gamekit is really just a wrapper around vast
cl-bodge API. For example, almost all draw-
functions are really just a reexported symbols from the canvas subsytem of cl-bodge. Actually,
if you look into sources of the gamekit, you will see, that it is itself just another system
of cl-bodge! That means, once you feel gamekit features are no longer enough to realize your
ideas, you can start using cl-bodge API right away. Keep in mind though: while
trivial-gamekit is considered stable, cl-bodge itself is a work in progress. API of the
latter is a subject to change, unlike gamekit’s one, which is promised to stay stable.