linci

Creating builds

linci> create build myproj

otherwise prefix all the commands in this doc with linci, or type linci shell to enter the shell.

The create build commmand will open vi with a template to be edited.

A brief description of targets...

The first two targets must be description: and environment:

description: descriptive text that is shown when you type linci list.
environment: may be blank, if populated linci sources a *.env file from /var/linci/environment/ before targets are run.

After this follows one-shot targets, typically these are to initailise the workspace with the code to be built.

init: by convention this is the target that checks out the repo, e.g. git clone https://github.com/me/myproj
clean: by convention this command wipes artifacts generated in the workspace, e.g. make clean

The targets:: entry is required, it separates one-shot targets from the main build.

targets::

From here on target are free form, the following is a typical build

sync: get latest code from the repo, typically something like git pull && git reset --hard origin/master
build: compile the code, typically make or run some grunt tasks, ant or maven
test: tests that have no external dependencies
publish: make code / binaries available outside the server

Run the build

After creating the build, initailise the workspace with.

linci> build myproj init

i.e. run the init target on its own.

Then run the build.

linci> build myproj

Console output

You will notice a surprising lack of output, generally scripts would be triggered by changes in source code, or run by cron by putting linci build myproj in crontab. Notification if the build was successful or failed is done via IRC.

When you first setup a build it is useful to get immediate feedback, rather than watching IRC.
Typing.

linci> ttyon

tells linci to echo success or failure messages to the shell, similar to the wall utility. On a busy server ttyon can result in so many messages using the shell is impossible so console output is off by default. ttyoff tuns off console notifications.

Each build generates logs, you can tail the log of the last build stated on the console with the llog command, to follow the log use llogf. To view the logs of past builds you can use the linci news utility which respects the PAGER environment variable. If you prefer, grep, vi or emacs, the logs are flat files on the server, no special tools are needed for debugging linci runs. This is kind of the point, logs are not in some stupid XML format. Each build generates a file called console.log.

Target naming conventions

It is suggested that the following names are used consistently.

package: create tar.gz or deb or rpm
install: install the code locally
deploy: install the code remotely
inttest: run integration tests, test with external dependencies
promote: push to another environemnt

There is no obligation to use the above conventions, the only targets that mean something to linci scripts are description: and environment: and the targets:: separator.

Jobs

Jobs are simplified builds that have one target called command.

description: a test job run by testbuild
environment:
command: echo "hello world"

Jobs are executed with.

linci> run myjob