README.md 4.85 KB
Newer Older
IOhannes m zmölnig's avatar
IOhannes m zmölnig committed
1
2
3
4
5
6
7
8
9
10
11
12
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:

13
14
- [externals that can be simply build with `make`](pd-lib-builder/)
- [externals that don't require any compilation](no-build/)
IOhannes m zmölnig's avatar
IOhannes m zmölnig committed
15
16
17
18
19
20
21
22
23
24
25

# 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
26
27
(such as the one being based on `pd-lib-builder`),
please follow the instructions in [pd-lib-builder/README.md](pd-lib-builder/README.md).
IOhannes m zmölnig's avatar
IOhannes m zmölnig committed
28

IOhannes m zmölnig's avatar
IOhannes m zmölnig committed
29
30
31
32
## externals that don't require any compilation

If your project doesn't require *any* compilation
(e.g. because it is an abstraction-only library),
33
please follow the instructions in [no-build/README.md](no-build/README.md).
IOhannes m zmölnig's avatar
IOhannes m zmölnig committed
34

IOhannes m zmölnig's avatar
IOhannes m zmölnig committed
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# 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