diff options
| -rw-r--r-- | docs/packaging.txt | 41 | ||||
| -rw-r--r-- | docs/publishing.txt | 13 | ||||
| -rw-r--r-- | docs/setup.sh.txt | 6 | ||||
| -rw-r--r-- | docs/templates.txt | 22 | ||||
| -rw-r--r-- | docs/using.txt | 19 | ||||
| -rw-r--r-- | docs/variables.txt | 6 | ||||
| -rw-r--r-- | manual.tex | 90 |
7 files changed, 88 insertions, 109 deletions
diff --git a/docs/packaging.txt b/docs/packaging.txt deleted file mode 100644 index 0a40749..0000000 --- a/docs/packaging.txt +++ /dev/null @@ -1,41 +0,0 @@ -My personal recommended way to package DSCIP is to do the following: - -Install all the scripts except setup.sh into /usr/share/charadon/dscip. -Next, install setup.sh to /usr/bin/setup-dscip. -Optionally, you can remove update.sh, if you wish for the user *not* to be -able to update dscip on their own outside of the packaging system. -And install the docs to your system's recommended documentation directory. -(Usually /usr/share/doc, or /usr/doc) - -If it's installed this way, instead of grabbing DSCIP from the remote git -repo, the setup script will copy the files from /usr/share/charadon/dscip. - -It requires no additional dependencies if I did things right, as it's written -in complete POSIX shell. Though, on illumos, it'll probably need GNU Coreutils -for realpath support. - -This is roughly what a package tree should look like. This is based on my -SlackBuild for Slackware. - -usr -├── bin -│ └── setup-dscip (setup.sh) -├── doc -│ └── dscip-0.9 -│ ├── LICENSE -│ ├── dscip.SlackBuild -│ ├── packaging.txt -│ ├── publishing.txt -│ ├── setup.sh.txt -│ ├── templates.txt -│ ├── using.txt -│ └── variables.txt -└── share - └── charadon - └── dscip - ├── build.sh - ├── config.sh - ├── dscip - ├── failed.sh - ├── post.sh - └── pre.sh diff --git a/docs/publishing.txt b/docs/publishing.txt deleted file mode 100644 index c3cf15c..0000000 --- a/docs/publishing.txt +++ /dev/null @@ -1,13 +0,0 @@ -Publishing build artifacts and logs. -================================================================================ -There are many ways you can publish artifacts, both privately and publically. - -Methods include: -Sending logs/artifacts through e-mail. -Uploading logs/artifacts to an FTP server. -Uploading logs/artifacts to an rsync server. -Uploading it through good ol HTTP. - -Basically, if there's a commandline utility for it, you can use it in the -post/failed.sh scripts. Refer to variables.txt for how to use variables for -organizing artifacts. diff --git a/docs/setup.sh.txt b/docs/setup.sh.txt deleted file mode 100644 index f0699ba..0000000 --- a/docs/setup.sh.txt +++ /dev/null @@ -1,6 +0,0 @@ -setup.sh is a script that helps automate or more easily set up a dscip -instance. If it is ran without arguments it enters Interactive Mode, where it -will prompt you questions. - -However, it can be used with command-line switches in Non-Interactive Mode. -For more info, use the -h switch on setup.sh diff --git a/docs/templates.txt b/docs/templates.txt deleted file mode 100644 index c28aecc..0000000 --- a/docs/templates.txt +++ /dev/null @@ -1,22 +0,0 @@ -In the setup script, you can specify a directory that contains templates. - -This directory can contain: -pre.sh -post.sh -build.sh -failed.sh -config.sh - -This can be helpful if you have multiple projects that build pretty much -exactly the same. Or are extremely similar and only require small -modifications, rather than writing the entire scripts from scratch. - -When using the setup.sh script, you can specify the directory by using --t /path/to/templates. A template directory looks like this: - -templates/ -├── build.sh -├── failed.sh -├── post.sh -├── config.sh -└── pre.sh diff --git a/docs/using.txt b/docs/using.txt deleted file mode 100644 index 29dbbf3..0000000 --- a/docs/using.txt +++ /dev/null @@ -1,19 +0,0 @@ -Using DSCIP -================================================================================ -Using DSCIP is extremely simple, there's two ways you can run it. -A. Running it as a cronjob that runs periodically. -B. Running it as a daemon that runs continually. - -Funcionally, these two methods work about the same, but depending on your -platform, one may be easier to set up than the other. I personally recommend -setting it up as a cronjob over a daemon. You can do this on most unix systems -by running `crontab -e -u build_user` and adding: -* * * * * /home/build_user/program/dscip - -As for how to make it run as a daemon, that depends on the platform you are -running it on, so refer to your OS's documentation for that. - -Be sure to change the variables in config.sh to suit your projects needs. - -Quirks: -When running it on windows, you should use MSYS2. diff --git a/docs/variables.txt b/docs/variables.txt deleted file mode 100644 index 38e8f4e..0000000 --- a/docs/variables.txt +++ /dev/null @@ -1,6 +0,0 @@ -Using Variables in the Build Scripts -================================================================================ -Every environment variable found in config.sh and the main dscip script can be -used in your build scripts. For example, you can use $CURRENT_COMMIT to create -a folder on your FTP server to put outputs into. Refer to the post.sh defaults -to see an example. diff --git a/manual.tex b/manual.tex index c0033de..623e866 100644 --- a/manual.tex +++ b/manual.tex @@ -31,9 +31,16 @@ This is the manual for the Dead Simple Continuous Integration POSIX program. @node Installing @chapter Installing - @cindex Installing +@cindex Installing Details on installing DSCIP onto various systems. - + @node Downloading + @section Downloading + @cindex Downloading + Currently, the upstream repo for DSCIP is located at this + @url{https://www.opencode.net/charadon/dscip, Git Repo}. If your OS + doesn't have DSCIP packaged, you can download the @command{setup.sh} + from the releases page, and use that to install dscip. Alternatively, + you can clone the git repo into whatever directory you want. @node Unix @section Unix @cindex Installing on Unix @@ -201,10 +208,89 @@ set MSYSTEM=MINGW64 @node Using Templates @section Using Templates @cindex 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 @option{-t} argument with + setup.sh. You find find an example of templates here at my + @url{https://www.opencode.net/charadon/my-dscip-templates-v1, Git Repo} @node Using +@chapter Using +@cindex Using + This chapter goes over how to actually use DSCIP. + @node Basic Variables + @section Basic Variables + @cindex Basic Variables + This section goes over variables that you can safely modify in + config.sh. + @subsection DSCIP_GITREPO + @cindex Basic Variables: DSCIP_GITREPO + This is the variable that determines what git repo DSCIP clones into + wrkdir. + @subsection DSCIP_NAME + @cindex Basic Variables: DSCIP_NAME + This variable determines the name of the program that's being build. + Mostly for use with the @command{post.sh} and @command{failed.sh} + scripts when publishing artifacts. + @subsection DSCIP_BRANCH + @cindex Basic Variables: DSCIP_BRANCH + This variable tells DSCIP which branch to clone. This is useful if + you develop in a branch other than master. + @subsection DSCIP_DAEMON + @cindex Basic Variables: DSCIP_DAEMON + This variable will tell DSCIP to not close, but rather stay open and + just sleep before re-running itself. Useful for Windows, if you + want DSCIP to run in shorter time periods than 60 seconds, or use + special features that your OS's init system gives. + @subsection DSCIP_DAEMON_FORK + @cindex Basic Variables: DSCIP_DAEMON_FORK + This variable tells DSCIP if it should run itself in the background. + Some init systems prefer one or the other, so consult your OS's + documentation. + @subsection DSCIP_SLEEP + @cindex Basic Variables: DSCIP_SLEEP + When in daemon mode, this controls how long DSCIP should wait + between attempted builds before checking for a new commit and + building if one exists. + @subsection DSCIP_OUTPUT_TO + @cindex Basic Variables: DSCIP_OUTPUT_TO + 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. + @node Advanced Variables + @section Advanced Variables + @cindex Advanced Variables + These are variables you should only change if you absolutely need to! + @subsection DSCIP_GITMODE + @cindex Advanced Variables: DSCIP_GITMODE + This tells DSCIP to, rather than delete the wrkdir and get a fresh + clone, to just pull changes. This is really only useful in + situations where you have limited bandwidth. + @subsection WORKING_DIRECTORY + @cindex Advanced Variables: WORKING_DIRECTORY + This should probably never be changed. The only situation that + *might* warrant changing it, is in a very restricted environment + where it *has* to run in a specific place. + @subsection DSCIP_@{PRE,BUILD,POST,FAILED@}_CMD + @cindex Advanced Variables: DSCIP_@{PRE,BUILD,POST,FAILED@}_CMD + These variables tell DSCIP where to find their respective scripts. Like + WORKING_DIRECTORY, this really shouldn't be changed and is really + only useful in situations that are very restrictive. + @subsection DSCIP_DISREGARD_COMMIT_CHECK + @cindex Advanced Variables: DSCIP_DISREGARD_COMMIT_CHECK + This variable tells DSCIP to ignore the commit check and just keep + rebuilding. This is useful for seeing if old/unmaintained software + will still build on modern systems. But other than that, should be + left off. + @subsection DSCIP_AUTO_UPDATE + @cindex Advanced Variables: DSCIP_AUTO_UPDATE + This variable tells DSCIP to run @command{update.sh}, and then run a + checksum on itself. If it's different from when it first launched, + It'll re-run itself. This is useful for manual installations. @node Platform Specifics |