\input texinfo @setfilename dscip.info @settitle Dead Simple Continuous Integration POSIX @copying 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 . @end copying @contents @node Top @top DSCIP Manual This is the manual for the Dead Simple Continuous Integration POSIX program. @menu * Installing:: * Using:: * Quirks:: * Index:: @end menu @node Installing @chapter 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 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. @node As a Package @subsection As a Package @cindex Unix: Installing Packaged DSCIP If your host OS packaged DSCIP correctly according to Packaging (@xref{Packaging}), these instructions should work. @enumerate @item Run @command{setup-dscip} in the terminal. See @command{setup-dscip -h} for more details. @item Add the new script as a cronjob or daemon. See your OS's manual for instructions on how to do so. @end enumerate And that's it! You're ready to go! @node Manually @subsection Manually @cindex Unix: Install Manually While not as simple as if it was packaged. The process is still not that hard. @enumerate @item Run @command{setup.sh}. See @command{setup.sh -h} for more details. @item Add the new script as a cronjob or daemon. See your OS's manual for instructions on how to do so. @end enumerate And that's it! You're ready to go! @node Windows @section Windows @cindex Installing on Windows Windows is a different beast from Unix. So it warrants it's own dedicated section. @node MSYS2 (Recommended) @subsection MSYS2 (Recommended) @cindex Windows: Installing on MSYS2 @enumerate @item Install @url{https://www.msys2.org, MSYS2} in whatever way you want. I recommend using @url{https://scoop.sh, Scoop}. @item Once MSYS2 is installed, run setup.sh (@command{setup.sh -h} for more info.). @item Next, we'll need to set it up as a service since Windows doesn't really have cronjobs. I recommend using @url{https://nssm.cc, NSSM} to create a service for Windows. @item Edit config.sh and set @env{DSCIP_DAEMON} to true, and set @env{DSCIP_DAEMON_FORK} to false. @item Next, create a batch/powershell script to launch MSYS2 to run the dscip script. Here's an example batch script: @example set MSYSTEM=MINGW64 "C:\Users\builder.DESKTOP-U8KQJI1\scoop\apps\msys2\current\usr\bin\bash" -l -c "path/to/dscip" @end example @item Next, run @command{nssm install } and set follow it's instructions. You can also use @url{https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create, sc.exe} if you'd rather not use NSSM. @item Then you just open services.msc and run it, or use @command{nssm start name-of-service}, if you went with NSSM. @end enumerate @node Only Bash @subsection Bash @cindex Windows: Installing with only Bash The easiest way to get Bash on Windows is to install git, so we'll be assuming that path. @enumerate @item Install @url{https://gitforwindows.org/, Git for Windows}, I recommend using @url{https://scoop.sh, Scoop}. @item Once Git is installed, you should be able to run @command{bash} from the command prompt or powershell. Once in Bash, run setup.sh (@command{setup.sh -h} for more info.) and install dscip. @item Once installed, you'll need to set up a service for it. I recommend using @url{https://nssm.cc, NSSM} for an easier time. @item Open config.sh and change @env{DSCIP_DAEMON} to true, and set @env{DSCIP_DAEMON_FORK} to false. @item Create a Batch or Powershell script, here's an example batch script: @* @example bash "C:\path\to\dscip" @end example @item Once the script is done being made, you can use NSSM to create the service, or @url{https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create, sc.exe}. @item Now just open services.msc or @command{nssm start } to start it. @end enumerate @node Packaging @section Packaging @cindex Packaging Packaging is pretty easy, just run @command{make install} and it'll do everything for you. You can use environment variables to change where certain things go though. @enumerate @item @env{PREFIX}: This specifies where on the system everything will go. By default it's /usr/local. @item @env{BINDIR}: The directory to install setup.sh to. When installed, it will change it's name to @command{setup-dscip}. @item @env{INFODIR}: The directory to install the manual. Default is @env{PREFIX}/share/info. @end enumerate @noindent This is the general layout that the Makefile defaults to: @example ├── bin │   └── setup-dscip (setup.sh) └── share ├── charadon │   └── dscip │   ├── build.sh │   ├── config.sh │   ├── dscip │   ├── failed.sh │   ├── post.sh │   └── pre.sh └── info └── dscip.info.gz @end example @* @noindent You'll note two things: @enumerate @item @command{update.sh} is not included. This is mainly mean't for non-package installs. Such as direct @command{git} clones, or using the @command{setup.sh} script on it's own. @item @env{SCRIPT_DIR} cannot be changed from it's default of $PREFIX/share/charadon/dscip. This is because the @command{setup.sh} script relies on the scripts being there to symlink to them. @end enumerate @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 Quirks @chapter Quirks @cindex Quirks This chapter goes over various quirks that have been discovered with DSCIP. None so far... @node Index @unnumbered Index @printindex cp @bye