Plugin/Handbook/README.md

The SenseGlove Unreal Engine Handbook

Prerequisites

• Brave Browser (for PDF generation; in case you have Brave installed in a non-conventional path, or you'd like to use a different Chromium-based browser you need to adjust the path inside the GNUmakefile).
• cygpath (Windows only) provided by Git for Windows.
• GNU Make.
• Git.
• PowerShell (Windows only) required only by the pack make target.
• Python3 along with venv and pip. For Windows, a version of WinPython is already shipped with this repo, so it's not an external requirement.
• Rsync and OpenSSH (cwRsync provides these for Windows) required only by the deploy make target.
• The Rust Toolchain and the Cargo package manager.
• Other common Unix utilities such as awk, cp, cut, date, find, grep, hostname, mkdir, mktemp, mv, scp, sed, ssh, sort, tr, and uname provided by most distors. On Windows these are mostly provided by Git for Windows.
• zip command (Linux only) required only by the pack make target.

Microsoft Windows Prerequisites Installation Notes

• Download and install Git for Windows.
• Download and install the Rust Toolchain.
• Download a without-guile binary build of GNU Make for Windows from ezwinports, e.g. make-4.4.1-without-guile-w32-bin.zip.
• make-*-without-guile-w32-bin.zip/* contents should be extracted and copied to your Git\mingw64\, e.g. C:\Program Files\Git\mingw64\, merging the folders, WITHOUT overwriting/replacing any existing files.
• After Git Bash installation, the changes to environment variables require a reboot. In order for these changes to take effect reboot the system, then proceed to the build section.
• Download and install cwRsync which is only required for the deploy make target. In case you won't intend to use that, this could be skipped.

How to preview, build, and deploy?

In order to generate the handbook, on either GNU/Linux and Microsoft Windows everything is done through running the make command. Simply entering the make or make help inside your desired terminal will show you all the available make targets:

$ make help

Available make targets:

  - make build
  - make clean
  - make deploy
  - make help
  - make info
  - make pack
  - make serve

make info

This target prints the build and version information.

make clean

This target cleans up the output directory for the generated handbook, which is the /Documentation folder.

make serve

This tatget could be used for viewing or live-previwing the handbook while editing simultaneously editing it. Simply run this tatget and leave your terminal open and inside your web browser of choice head to http://localhost:8000/. You can modify the handbook source code inside any text editor and upon saving your web browser will refresh in realtime once a change is detected.

make build

This tatget builds the final handbook and outputs it to the /Documentation folder.

If you're building a release handbook, please make sure:

• You are either on a release tag, e.g. v2.1.0, or on the master branch.
• No commit has been made since the targeted tag.
• The Git tree state is clean.
• The Git version and plugin version match each other.

If you're building an unstable handbook for the next release, please make sure:

• You're building from the dev branch.
• The Git version value evaluates to empty.

make deploy

This tatget is used to build and upload the final draft of the handbook. This tatget first runs the clean target and then the build target; and only then attempts to upload the content. Thus, any rule that applies to the build target, will apply to this target as well.

Noete: Building on Windows requires sourcing the deployment configuration file, otherwise the deployment will fail; e.g.:

$ source /c/Users/mamadou/AppData/Local/SenseGlove/ue-handbook/deploy.conf && make deploy

Also, on Windows you probably need to adjust the follwoing variables at the top of the GNUmakefile:

SG_RSYNC_BIN_PATH_WINDOWS		:=	C:\Program Files\cwrsync\bin
SG_RSYNC_BINARY_PATH_WINDOWS		:=	$(SG_RSYNC_BIN_PATH_WINDOWS)\rsync.exe
SG_RSYNC_SSH_BINARY_PATH_WINDOWS	:=	$(SG_RSYNC_BIN_PATH_WINDOWS)\ssh.exe

make pack

This target is meant to be used by the sgum-packager utility located in the Packager folder in order to deploy the documentation in various formats along with the plugin to the Unreal Engine Marketplace.