manual.tex: Updated manual to add info about the new date variables.

2 files changed, 214 insertions, 2 deletions

diff --git a/dscip.info b/dscip.info
index 24454dc..55bccb9 100644
--- a/dscip.info
+++ b/dscip.info
Binary files differdiff --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 <<EOF
+open 192.168.1.5
+user username password
+mkdir $DSCIP_NAME
+cd $DSCIP_NAME
+mkdir $CURRENT_COMMIT
+cd $CURRENT_COMMIT
+mkdir $(uname)
+cd $(uname)
+put $WORKING_DIRECTORY/output.txt output-failed.txt
+close
+bye
+EOF
+			@end example
+		@node post_dot_sh
+		@subsection post.sh
+		@cindex Scripts: post.sh
+			This script tells DSCIP what to do if the build succeeded. Like
+			pre.sh, it must return 0 or else DSCIP will abort. @*Example:@*
+			@example
+#!/bin/sh
+
+set -eu
+
+# Execute commands after building. Like pushing to an FTP server.              #
+# Example below. #
+
+# TAR up the program.                                                          #
+bsdtar -a -cf \
+$DSCIP_NAME-$(uname)-$(uname -r)_$(uname -m)-$CURRENT_COMMIT.tar.xz app/
+
+# Send the artifacts to an FTP server.                                         #
+ftp -in <<EOF
+open 192.168.255.255
+user username pAssw0rd
+mkdir $DSCIP_NAME
+cd $DSCIP_NAME
+mkdir $CURRENT_COMMIT
+cd $CURRENT_COMMIT
+mkdir $(uname)
+cd $(uname)
+put $DSCIP_NAME-$(uname)-$(uname -r)_$(uname -m)-$CURRENT_COMMIT.tar.xz
+put $WORKING_DIRECTORY/output.txt output-success.txt
+close
+bye
+EOF
+
+exit 0
+			@end example
 	@node Basic Variables
 	@section Basic Variables
 	@cindex Basic Variables
 		This section goes over variables that you can safely modify in
-		config.sh.
+		config.sh and/or use in your scripts.
 		@subsection DSCIP_GITREPO
 		@cindex Basic Variables: DSCIP_GITREPO
 			This is the variable that determines what git repo DSCIP clones into
-			wrkdir.
+			wrkdir. It should be noted that this isn't limited to a remote URL.
+			It can also clone from a local system git repo. This can be useful
+			if you want to forbid internet access to the builder user.
 		@subsection DSCIP_NAME
 		@cindex Basic Variables: DSCIP_NAME
 			This variable determines the name of the program that's being build.
@@ -390,6 +584,24 @@ set MSYSTEM=MINGW64
 			This variable tells DSCIP where to put logs. By default it puts all
 			output into output.txt. This is useful if, for example, you're
 			running DSCIP in daemon mode, and need to store logs somewhere else.
+		@subsection DSCIP_DATE_FORMAT
+		@cindex Basic Variables: DSCIP_DATE_FORMAT
+			This variable tells DSCIP how it should format @env{COMMIT_DATE}. See
+			@command{strftime(3)} for more information of time codes.
+		@subsection LAST_COMMIT
+		@cindex Basic Variables: LAST_COMMIT
+			This variable tells DSCIP what the last commit was. This variable
+			should be treated as *readonly* and should never be modified.
+		@subsection CURRENT_COMMIT
+		@cindex Basic Variables: CURRENT_COMMIT
+			This variable tells DSCIP what commit it's currently building. This
+			variable like LAST_COMMIT should be treated as *readonly* and should
+			never be modified.
+		@subsection COMMIT_DATE
+		@cindex Basic Variables: COMMIT_DATE
+			This variable is the date that the commit was created on. This can
+			be used in your post scripts to organize artifacts if you wish. This
+			string is formatted with @env{DSCIP_DATE_FORMAT} above.
 	@node Advanced Variables
 	@section Advanced Variables
 	@cindex Advanced Variables