92 lines
4.8 KiB
Markdown
92 lines
4.8 KiB
Markdown
# 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](https://gitforwindows.org/).
|
|
- 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](https://winpython.github.io/) is already shipped with this repo, so it's not an external requirement.
|
|
- Rsync and OpenSSH ([cwRsync](https://itefix.net/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](https://gitforwindows.org/).
|
|
- `zip` command (Linux only) required only by the `pack` make target.
|
|
|
|
### Microsoft Windows Prerequisites Installation Notes
|
|
|
|
- Download and install [Git for Windows](https://gitforwindows.org/).
|
|
- Download and install [the Rust Toolchain](https://rustup.rs/).
|
|
- Download [a without-guile binary build of GNU Make for Windows from ezwinports](https://sourceforge.net/projects/ezwinports/files/), e.g. <code>make-4.4.1-without-guile-w32-bin.zip</code>.
|
|
- <code>make-\*-without-guile-w32-bin.zip/*</code> contents should be extracted and copied to your <code>Git\\mingw64\\</code>, e.g. <code>C:\\Program Files\\Git\\mingw64\\</code>, 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](https://itefix.net/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 <code>make</code> command. Simply entering the <code>make</code> or <code>make help</code> inside your desired terminal will show you all the available make targets:
|
|
|
|
```sh
|
|
$ 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 <code>/Documentation</code> 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 <code>http://localhost:8000/</code>. 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 <code>/Documentation</code> 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 <code>clean</code> target and then the <code>build</code> target; and only then attempts to upload the content. Thus, any rule that applies to the <code>build</code> 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.:
|
|
|
|
```sh
|
|
$ 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`:
|
|
|
|
```make
|
|
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](../Packager) folder in order to deploy the documentation in various formats along with the plugin to [Fab](https://www.fab.com/).
|