This is dscip.info, produced by makeinfo version 6.8 from manual.tex.
Creative Commons Legal Code
CC0 1.0 Universal
CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.
Statement of Purpose
The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator
and subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").
Certain owners wish to permanently relinquish those rights to a Work for
the purpose of contributing to a commons of creative, cultural and
scientific works ("Commons") that the public can reliably and without fear
of later claims of infringement build upon, modify, incorporate in other
works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes.
These owners may contribute to the Commons to promote the ideal of a free
culture and the further production of creative, cultural and scientific
works, or to gain reputation or greater distribution for their Work in
part through the use and efforts of others.
For these and/or other purposes and motivations, and without any
expectation of additional consideration or compensation, the person
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its
terms, with knowledge of his or her Copyright and Related Rights in the
Work and the meaning and intended legal effect of CC0 on those rights.
1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not
limited to, the following:
i. the right to reproduce, adapt, distribute, perform, display,
communicate, and translate a Work;
ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or
likeness depicted in a Work;
iv. rights protecting against unfair competition in regards to a Work,
subject to the limitations in paragraph 4(a), below;
v. rights protecting the extraction, dissemination, use and reuse of data
in a Work;
vi. database rights (such as those arising under Directive 96/9/EC of the
European Parliament and of the Council of 11 March 1996 on the legal
protection of databases, and under any national implementation
thereof, including any amended or successor version of such
directive); and
vii. other similar, equivalent or corresponding rights throughout the
world based on applicable law or treaty, and any national
implementations thereof.
2. Waiver. To the greatest extent permitted by, but not in contravention
of, applicable law, Affirmer hereby overtly, fully, permanently,
irrevocably and unconditionally waives, abandons, and surrenders all of
Affirmer's Copyright and Related Rights and associated claims and causes
of action, whether now known or unknown (including existing as well as
future claims and causes of action), in the Work (i) in all territories
worldwide, (ii) for the maximum duration provided by applicable law or
treaty (including future time extensions), (iii) in any current or future
medium and for any number of copies, and (iv) for any purpose whatsoever,
including without limitation commercial, advertising or promotional
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
member of the public at large and to the detriment of Affirmer's heirs and
successors, fully intending that such Waiver shall not be subject to
revocation, rescission, cancellation, termination, or any other legal or
equitable action to disrupt the quiet enjoyment of the Work by the public
as contemplated by Affirmer's express Statement of Purpose.
3. Public License Fallback. Should any part of the Waiver for any reason
be judged legally invalid or ineffective under applicable law, then the
Waiver shall be preserved to the maximum extent permitted taking into
account Affirmer's express Statement of Purpose. In addition, to the
extent the Waiver is so judged Affirmer hereby grants to each affected
person a royalty-free, non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to exercise Affirmer's Copyright and
Related Rights in the Work (i) in all territories worldwide, (ii) for the
maximum duration provided by applicable law or treaty (including future
time extensions), (iii) in any current or future medium and for any number
of copies, and (iv) for any purpose whatsoever, including without
limitation commercial, advertising or promotional purposes (the
"License"). The License shall be deemed effective as of the date CC0 was
applied by Affirmer to the Work. Should any part of the License for any
reason be judged legally invalid or ineffective under applicable law, such
partial invalidity or ineffectiveness shall not invalidate the remainder
of the License, and in such case Affirmer hereby affirms that he or she
will not (i) exercise any of his or her remaining Copyright and Related
Rights in the Work or (ii) assert any associated claims and causes of
action with respect to the Work, in either case contrary to Affirmer's
express Statement of Purpose.
4. Limitations and Disclaimers.
a. No trademark or patent rights held by Affirmer are waived, abandoned,
surrendered, licensed or otherwise affected by this document.
b. Affirmer offers the Work as-is and makes no representations or
warranties of any kind concerning the Work, express, implied,
statutory or otherwise, including without limitation warranties of
title, merchantability, fitness for a particular purpose, non
infringement, or the absence of latent or other defects, accuracy, or
the present or absence of errors, whether or not discoverable, all to
the greatest extent permissible under applicable law.
c. Affirmer disclaims responsibility for clearing rights of other persons
that may apply to the Work or any use thereof, including without
limitation any person's Copyright and Related Rights in the Work.
Further, Affirmer disclaims responsibility for obtaining any necessary
consents, permissions or other rights required for any use of the
Work.
d. Affirmer understands and acknowledges that Creative Commons is not a
party to this document and has no duty or obligation with respect to
this CC0 or use of the Work.
File: dscip.info, Node: Top, Next: Installing, Up: (dir)
Dead Simple Continuous Integration POSIX Manual
***********************************************
This is the manual for the Dead Simple Continuous Integration POSIX
program.
Dead Simple Continuous Integration POSIX Manual by Charadon
(DSCIP Manual for short.)
To the extent possible under law, the person who associated CC0 with
DSCIP Manual has waived all copyright and related or neighboring rights
to DSCIP Manual.
You should have received a copy of the CC0 legalcode along with this
work. If not, see:
.
* Menu:
* Installing::
* Using::
* Quirks::
* Manual's License::
* Index::
File: dscip.info, Node: Installing, Next: Using, Prev: Top, Up: Top
1 Installing
************
Details on installing DSCIP onto various systems.
* Menu:
* Downloading::
* Unix::
* Windows::
* Packaging::
* Using Templates::
File: dscip.info, Node: Downloading, Next: Unix, Up: Installing
1.1 Downloading
===============
Currently, the upstream repo for DSCIP is located at this Git Repo
(https://www.opencode.net/charadon/dscip). If your OS doesn't have
DSCIP packaged, you can download the 'setup.sh' from the releases page,
and use that to install dscip. Alternatively, you can clone the git
repo into whatever directory you want.
File: dscip.info, Node: Unix, Next: Windows, Prev: Downloading, Up: Installing
1.2 Unix
========
In this section, Unix refers to systems that are similar in nature to
the old System V Unix or is POSIX in nature. This would include: Linux,
BSD, Mac, Haiku, and Illumos.
The instructions will pretty much be the same for all systems.
* Menu:
* As a Package::
* Manually::
File: dscip.info, Node: As a Package, Next: Manually, Up: Unix
1.2.1 As a Package
------------------
If your host OS packaged DSCIP correctly according to Packaging (*Note
Packaging::), these instructions should work.
1. Run 'setup-dscip' in the terminal. See 'setup-dscip -h' for more
details.
2. Add the new script as a cronjob or daemon. See your OS's manual
for instructions on how to do so.
And that's it! You're ready to go!
File: dscip.info, Node: Manually, Prev: As a Package, Up: Unix
1.2.2 Manually
--------------
While not as simple as if it was packaged. The process is still not
that hard.
1. Run 'setup.sh'. See 'setup.sh -h' for more details.
2. Add the new script as a cronjob or daemon. See your OS's manual
for instructions on how to do so.
And that's it! You're ready to go!
File: dscip.info, Node: Windows, Next: Packaging, Prev: Unix, Up: Installing
1.3 Windows
===========
Windows is a different beast from Unix. So it warrants it's own
dedicated section.
* Menu:
* MSYS2 (Recommended)::
* Only Bash::
File: dscip.info, Node: MSYS2 (Recommended), Next: Only Bash, Up: Windows
1.3.1 MSYS2 (Recommended)
-------------------------
1. Install MSYS2 (https://www.msys2.org) in whatever way you want. I
recommend using Scoop (https://scoop.sh).
2. Once MSYS2 is installed, run setup.sh ('setup.sh -h' for more
info.).
3. Next, we'll need to set it up as a service since Windows doesn't
really have cronjobs. I recommend using NSSM (https://nssm.cc) to
create a service for Windows.
4. Edit config.sh and set 'DSCIP_DAEMON' to true, and set
'DSCIP_DAEMON_FORK' to false.
5. Next, create a batch/powershell script to launch MSYS2 to run the
dscip script. Here's an example batch script:
set MSYSTEM=MINGW64
"C:\Users\builder.DESKTOP-U8KQJI1\scoop\apps\msys2\current\usr\bin\bash" -l -c "path/to/dscip"
6. Next, run 'nssm install ' and set follow it's
instructions. You can also use sc.exe
(https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create)
if you'd rather not use NSSM.
7. Then you just open services.msc and run it, or use 'nssm start
name-of-service', if you went with NSSM.
File: dscip.info, Node: Only Bash, Prev: MSYS2 (Recommended), Up: Windows
1.3.2 Bash
----------
The easiest way to get Bash on Windows is to install git, so we'll be
assuming that path.
1. Install Git for Windows (https://gitforwindows.org/), I recommend
using Scoop (https://scoop.sh).
2. Once Git is installed, you should be able to run 'bash' from the
command prompt or powershell. Once in Bash, run setup.sh
('setup.sh -h' for more info.) and install dscip.
3. Once installed, you'll need to set up a service for it. I
recommend using NSSM (https://nssm.cc) for an easier time.
4. Open config.sh and change 'DSCIP_DAEMON' to true, and set
'DSCIP_DAEMON_FORK' to false.
5. Create a Batch or Powershell script, here's an example batch
script:
bash "C:\path\to\dscip"
6. Once the script is done being made, you can use NSSM to create the
service, or sc.exe
(https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create).
7. Now just open services.msc or 'nssm start ' to
start it.
File: dscip.info, Node: Packaging, Next: Using Templates, Prev: Windows, Up: Installing
1.4 Packaging
=============
Packaging is pretty easy, just run 'make install' and it'll do
everything for you. You can use environment variables to change where
certain things go though.
1. 'PREFIX': This specifies where on the system everything will go.
By default it's /usr/local.
2. 'BINDIR': The directory to install setup.sh to. When installed, it
will change it's name to 'setup-dscip'.
3. 'INFODIR': The directory to install the manual. Default is
'PREFIX'/share/info.
This is the general layout that the Makefile defaults to:
.
|-- bin
| `-- setup-dscip (setup.sh)
`-- share
|-- charadon
| `-- dscip
| |-- build.sh
| |-- config.sh
| |-- dscip
| |-- failed.sh
| |-- post.sh
| `-- pre.sh
`-- info
`-- dscip.info.gz
You'll note two things:
1. 'update.sh' is not included. This is mainly mean't for non-package
installs. Such as direct 'git' clones, or using the 'setup.sh'
script on it's own.
2. 'SCRIPT_DIR' cannot be changed from it's default of
$PREFIX/share/charadon/dscip. This is because the 'setup.sh'
script relies on the scripts being there to symlink to them.
File: dscip.info, Node: Using Templates, Prev: Packaging, Up: Installing
1.5 Using Templates
===================
Templates are an easy way to quickly get a DSCIP instance up and
running. Since most developers tend to have all their projects build
almost the exact same way, you can easily create a git repo with your
DSCIP scripts and have the setup script copy them over. You can point
to the directory containing your templates by using the '-t' argument
with setup.sh. You find find an example of templates here at my Git
Repo (https://www.opencode.net/charadon/my-dscip-templates-v1)
File: dscip.info, Node: Using, Next: Quirks, Prev: Installing, Up: Top
2 Using
*******
This chapter goes over how to actually use DSCIP.
* Menu:
* Scripts::
* Basic Variables::
* Advanced Variables::
File: dscip.info, Node: Scripts, Next: Basic Variables, Up: Using
2.1 Scripts
===========
This section covers all the scripts in DSCIP, what they do, and with
examples.
* Menu:
* config_dot_sh::
* setup_dot_sh::
* update_dot_sh::
* pre_dot_sh::
* build_dot_sh::
* failed_dot_sh::
* post_dot_sh::
File: dscip.info, Node: config_dot_sh, Next: setup_dot_sh, Up: Scripts
2.1.1 config.sh
---------------
'config.sh' is where all the variables for dscip are stored. Any
variable in here can be used in any other script. See *Note Basic
Variables::.
Example:
#!/bin/sh
# Variables that control the program. #
# GIT Repo #
export DSCIP_GITREPO="https://www.example.com/example/example.git"
export DSCIP_NAME="Example"
# GIT MODE: #
# pull: Doesn't delete previous clone and just pulls changes. #
# clone: Deletes previous clone, and creates a fresh clone. #
export DSCIP_GITMODE="clone"
# Branch to check #
export DSCIP_BRANCH="master"
# The directory where all the scripts are. By default tries to detect where #
# automatically. #
WORKING_DIRECTORY="$(pwd -P)"
export WORKING_DIRECTORY
# Commands to run before building. #
export DSCIP_PRE_CMD="$WORKING_DIRECTORY/pre.sh"
# Commands to run to build program. #
export DSCIP_BUILD_CMD="$WORKING_DIRECTORY/build.sh"
# Commands to run after building has succeeded. #
export DSCIP_POST_CMD="$WORKING_DIRECTORY/post.sh"
# Commands to run after building has failed.
export DSCIP_FAILED_CMD="$WORKING_DIRECTORY/failed.sh"
# Daemon mode options #
export DSCIP_DAEMON="false" # If daemon mode should be enabled or not. #
export DSCIP_DAEMON_FORK="true" # If the daemon should run in the background. #
export DSCIP_SLEEP="60" # How many seconds before the daemon re-runs itself. #
# etc #
export DSCIP_DISREGARD_COMMIT_CHECK="false" # If the script should just rebuild even #
# if upstream has not updated. #
export DSCIP_OUTPUT_TO="$WORKING_DIRECTORY/output.txt" # Output to file, default is output.txt
# Automatically update DSCIP?
export DSCIP_AUTO_UPDATE="false"
File: dscip.info, Node: setup_dot_sh, Next: update_dot_sh, Prev: config_dot_sh, Up: Scripts
2.1.2 setup.sh
--------------
This script will handle the downloading, installing/symlinking, and
configuration of a DSCIP instance. It has two modes of operation:
1. Interactive Mode: If no argument is supplied, it will ask the user
questions on how it wants to set up the dscip instance.
2. Non-interactive Mode: If arguments are supplied, it will use those
arguments to create a DSCIP instance.
See 'setup.sh -h' for more info. This script can also go by the name
'setup-dscip' if it's packaged.
Example:
./setup.sh -n "Pong-C" -d /home/builder/Pong-C -u "https://opencode.net/charadon/pong-c" -b master -t /home/builder/templates
File: dscip.info, Node: update_dot_sh, Next: pre_dot_sh, Prev: setup_dot_sh, Up: Scripts
2.1.3 update.sh
---------------
This script updates the 'dscip' script. It shouldn't be present if
packaged for a system. It's only useful manual installations.
File: dscip.info, Node: pre_dot_sh, Next: build_dot_sh, Prev: update_dot_sh, Up: Scripts
2.1.4 pre.sh
------------
This script contains the commands to run *before* the build commands.
This script can do things such as:
1. Update the System.
2. Grab assets from a remote URL not part of the git repo.
3. Probe to see if certain services are up and running. Such as a FTP
server to upload artifacts to.
If this script doesn't exit with 0, then DSCIP aborts. Another thing to
note, is that DSCIP will run whatever the shebang is, so this script can
be made in other languages, such as Perl, Python, Powershell, Batch, C
Shell, etc.
Example:
#!/bin/sh
set -eu
# Execute commands before building.
# Below is an example.
# Build user implied to have sudo access to apt update and upgrade
sudo apt update -y
sudo apt upgrade -y
# Including assets with game code is usually a bad idea, so we grab the assets
# from a mirror.
wget https://www.example.com/project/game_assets.zip
unzip game_assets.zip
exit 0
File: dscip.info, Node: build_dot_sh, Next: failed_dot_sh, Prev: pre_dot_sh, Up: Scripts
2.1.5 build.sh
--------------
This script contains the build commands for your project. If the script
doesn't return 0, it will run *Note 'failed.sh': failed_dot_sh,
otherwise, it will run *Note 'post.sh': post_dot_sh.
Example:
#!/bin/sh
set -eu
# Insert build commands in here. #
# If you're feeling particular paranoid, you can make it chroot here. #
./configure
make -j4
make DESTDIR=app install
exit 0
File: dscip.info, Node: failed_dot_sh, Next: post_dot_sh, Prev: build_dot_sh, Up: Scripts
2.1.6 failed.sh
---------------
This script tells DSCIP what to do if the build failed. Like pre.sh, it
must return 0 or else DSCIP will abort.
Example:
#!/bin/sh
set -eu
# This script determines what to do if the build failed.
# Below is an example of uploading the output.txt to an ftp server.
ftp -in <