Commit 10862ff2 authored by IOhannes m zmölnig's avatar IOhannes m zmölnig
Browse files

added general README

parent 27ffcbbb
Continuous Integration for Pd
=============================
Continous Integraton (CI) will automatically build your software whenever you
`git push` your code to a (CI-enabled) git-server.
This project targets building externals for Pure Data ([Pd][]), using the
CI-infrastructure provided by the Institute of Electronic Music and Acoustics
([IEM][]).
Currently this project targets two types of externals:
- externals that can be simply build with "make"
# choose the type of your external
This document explains the general workflow when building externals using IEM's CI.
Depending on the type of your external,
you should read the per-type documentation.
## externals that can be simply build with `make`
If your project uses a simple `make` based buildsystem
(such as the one being based on [pd-lib-builder][]),
please follow the instructions in [pd-lib-builder/README.md]
# what it does
The CI-configuration found in this project builds Pd-externals on various
platforms (Linux, macOS, Win32, Win64).
The IEM-CI infrastructure provides special build-bots that do native builds
(e.g. the Win64 builds are run on a Win64 (virtual) machine).
Ordinary builds will expire after 7 days.
If you use `git tag` to tag a new release (don't forget to `git push --tags`),
these builds will be kept indefinitely.
Optionally, tagged releases can also be uploaded automatically to [deken][] (the
Pd package download server).
# how to use it
- If you have created your project a while ago, you should first adjust the path to your CI-configuration
- Go to `https://git.iem.at/<GROUP>/<PROJECT>/settings/ci_cd`
- In the *General pipelines* section set the *Custum CI config path* to `.git-ci/gitlab-iem.yml`
- *Note: for newly created projects this is already the default*
- In your repository, create a directory `.git-ci/` and therein add a script
`gitlab-iem.yml`.
If you are using `pd-lib-builder` for building your project, the content of your `gitlab-iem.yml`
should look like this:
~~~yml
---
include:
- https://git.iem.at/pd/iem-ci/raw/master/pd-lib-builder/gitlab-iem.yml
~~~
If your project doesn't need to build anything and has on `Makefile` (e.g. because
this is a abstraction-only library), use this instead:
~~~yml
---
include:
- https://git.iem.at/pd/iem-ci/raw/master/no-build/gitlab-iem.yml
~~~
- Push the new file to the repository:
~~~sh
git add .git-ci/gitlab-iem.yml
git commit .git-ci/gitlab-iem.yml -m "[ci] added CI-configuration"
git push
~~~
- Hack away and Push new commits
## build products
(Successfull) builds will create a ZIP-file (so called *artifacts*).
These ZIP-files are available for download e.g.
from `https://git.iem.at/<GROUP>/<PROJECT>/pipelines/latest` (on the *Jobs*-Tab)
Download one of the ZIP-files, and extract it to a place where Pd can find it to start using it right away.
The `deken` job (which is run as a final stage for tagged releases) will produce a ZIP-file containing all
the `.dek`-files generated by the build.
## how to automatically upload tagged releases to deken
If you want you can automatically upload successfull builds for tagged releases.
On `https://git.iem.at/<GROUP>/<PROJECT>/settings/ci_cd` in the *Variables*
section, set two variables
| variable name | description |
| -------------- | ----------------------------------------- |
|`DEKEN_USERNAME`| a username to upload to deken |
|`DEKEN_PASSWORD`| the password associated with the username |
Please do not use any valuable username/password!
## customizing builds
The CI-configuration should work out of the box.
However, there are a few options to customize the behaviour.
### Library directory
The configuration assumes that the generated Pd-library has the same name as the project (that is:
the last componenent of the repository URL).
If this is not the case, set the `IEM_CI_PROJECT_NAME` variable accordingly (for **all** jobs).
This is necessary to tell the build-process where to find the build result.
E.g. if your repository has the name `pd-superlib`, but the library is really called `superlib`,
you would do something like this:
~~~yml
---
include:
- https://git.iem.at/pd/iem-ci/raw/master/pd-lib-builder/gitlab-iem.yml
variables:
IEM_CI_PROJECT_NAME: superlib
~~~
# who can use it
The IEM-CI infrastructure can (currently) only be used for projects hosted on
https://git.iem.at/
[Pd]: https://puredata.info/
[IEM]: https://iem.at/
[pd-lib-builder]: https://github.com/pure-data/pd-lib-builder/
[deken]: https://deken.puredata.info/
[gitlab-iem.yml]: https://git.iem.at/pd/iem-ci/gitlab-iem.yml
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment