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

added no-build README.md

parent 10862ff2
......@@ -11,6 +11,7 @@ CI-infrastructure provided by the Institute of Electronic Music and Acoustics
Currently this project targets two types of externals:
- externals that can be simply build with "make"
- externals that don't require any compilation
# choose the type of your external
......@@ -25,6 +26,12 @@ 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]
## externals that don't require any compilation
If your project doesn't require *any* compilation
(e.g. because it is an abstraction-only library),
please follow the instructions in [no-build/README.md]
# what it does
The CI-configuration found in this project builds Pd-externals on various
......
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 sub-project targets externals that don't require any compilation
(such as abstraction-only externals).
# what it does
The CI-configuration found in this project creates a [deken][]-package from
your project-directory.
Ordinary packages 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).
## step-by-step
- create an archive of your project in the [deken][]-format
- for tagged releases only:
- if `DEKEN_USERNAME` and `DEKEN_PASSWORD` are set, attempt to upload the
deken packages to the 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` with the following contents:
~~~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*)
with the compiled binaries (as created by a `make install` step).
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 name
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:
~~~yml
---
include:
- https://git.iem.at/pd/iem-ci/raw/master/no-build/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/
[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