added no-build README.md

README.md

@@ -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

no-build/README.md

+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