From 0600543081c9ba9f4b6727895881064307da5365 Mon Sep 17 00:00:00 2001 From: Charadon Date: Sat, 8 Oct 2022 15:05:58 -0400 Subject: manual.tex: Updated manual to add info about the new date variables. --- dscip.info | Bin 7581 -> 36297 bytes manual.tex | 216 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 214 insertions(+), 2 deletions(-) diff --git a/dscip.info b/dscip.info index 24454dc..55bccb9 100644 Binary files a/dscip.info and b/dscip.info differ diff --git a/manual.tex b/manual.tex index a35e9f0..7913e1d 100644 --- a/manual.tex +++ b/manual.tex @@ -351,15 +351,209 @@ set MSYSTEM=MINGW64 @chapter Using @cindex Using This chapter goes over how to actually use DSCIP. + @node Scripts + @section Scripts + @cindex Using: Scripts + This section covers all the scripts in DSCIP, what they do, and with + examples. + @node config_dot_sh + @subsection config.sh + @cindex Scripts: config.sh + @command{config.sh} is where all the variables for dscip are stored. + Any variable in here can be used in any other script. See + @xref{Basic Variables}.@*Example: + @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" + @end example + @node setup_dot_sh + @subsection setup.sh + @cindex Scripts: setup.sh + This script will handle the downloading, installing/symlinking, and + configuration of a DSCIP instance. It has two modes of operation: + @enumerate + @item + Interactive Mode: If no argument is supplied, it will ask the + user questions on how it wants to set up the dscip instance. + @item + Non-interactive Mode: If arguments are supplied, it will use + those arguments to create a DSCIP instance. + @end enumerate + @noindent @* + See @command{setup.sh -h} for + more info. This script can also go by the name @command{setup-dscip} + if it's packaged.@*@* Example: + @example +./setup.sh -n "Pong-C" -d /home/builder/Pong-C -u "https://opencode.net/charadon/pong-c" -b master -t /home/builder/templates + @end example + @node update_dot_sh + @subsection update.sh + @cindex Scripts: update.sh + This script updates the @command{dscip} script. It shouldn't be + present if packaged for a system. It's only useful manual + installations. + @node pre_dot_sh + @subsection pre.sh + @cindex Scripts: pre.sh + This script contains the commands to run *before* the build + commands. This script can do things such as: + @enumerate + @item + Update the System. + @item + Grab assets from a remote URL not part of the git repo. + @item + Probe to see if certain services are up and running. Such as a + FTP server to upload artifacts to. + @end enumerate + @* + @noindent + 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: + @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 + @end example + @node build_dot_sh + @subsection build.sh + @cindex Scripts: build.sh + This script contains the build commands for your project. If the + script doesn't return 0, it will run @xref{failed_dot_sh, + @command{failed.sh}}, otherwise, it will run + @xref{post_dot_sh,@command{post.sh}}.@*Example:@* + @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 + @end example + @node failed_dot_sh + @subsection failed.sh + @cindex Scripts: 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:@* + @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 <