Add a quick guide for building SugarCube

devNotes/sugarcube stuff/building sugarcube.txt

+This brief how-to guides through patching and building sugarcube (https://bitbucket.org/tmedwards/sugarcube)
+for the Free Cities. Sugarcube sources can be obtained locally either by cloning its Mercurial
+repository or downloading source archive from bitbucket (https://bitbucket.org/tmedwards/sugarcube/downloads/).
+
+
+Prerequisites (listed NOT in the installation order, please read the list to the end first):
+1. Node.js with npm (https://nodejs.org).
+2. Mercurial (https://www.mercurial-scm.org/) if you want to clone the sugarcube repository (so it is
+optional). Please note that when downloading Windows version, the Mercurial web site lists source
+download first (and linked it to the main page), while we need binaries.
+3. To build some packages, Node.js requires python and a C/C++ compiler. On Windows you may want to
+install Visual Studio (or just the build tools) and Python 2.7 first. As of now, SugarCube does not
+depend on any of such packages.
+
+Windows: please choose to make the tools accessible from anywhere by allowing installers to modify
+the PATH environment variable.
+
+Retrieving SugarCube sources and preparing build environment for it.
+1a. If you opted to use Mercurial, open a terminal window where you want to clone the repository, and
+run the following command:
+	hg clone https://bitbucket.org/tmedwards/sugarcube
+Change working directory into the cloned repository.
+Now choose the branch. Let's suppose we want the lates officially released version 2. The branch name
+is "v2-release" then:
+	hg checkout v2-release
+Please note that branch switching in Mercurial requires a clean local tree (without modifications).
+To achieve that, run:
+	hg update --clean
+
+1b. If you decided not to use Mercurial, you can download a snapshot of a branch or a tag from the
+"Downloads" tab of the bitbucket repository page. Unpack it and open a terminal in the directory
+with the source files.
+
+2. The last step we need is downloading required JavaScript libraries that are used during the build.
+Run the node package manager (npm) in the repository:
+	npm install
+
+CAUTION: dependencies list (located in the package.json file in the repository root) may change from
+commit to commit and it differs between branches! Make sure to istall correct dependencies after
+switching working brach.
+
+
+Patching and building SugarCube.
+
+3a. If you opted to use Mercurial, use it to apply the patch:
+	hg patch --no-commit <full path to sugarcube-fc-changes.patch>
+
+3b. If you do not use Mercurial:
+	patch -p1 < <full path to sugarcube-fc-changes.patch>
+
+Building
+Run the build.js script. If you use Git bash, you can run the build.js file directly, otherwise run
+it as "node build.js". See "build.js -h" for options, but reasonable sets are the following.
+For release version:
+	./build.js -b 2
+and for the debug version:
+	./build.js -b 2 -u -d
+
+Find result files in the dist directory.
+
+
+APPENDIX Lists required steps very briefly.
+
+1. Clone Sugarube repo: hg clone https://bitbucket.org/tmedwards/sugarcube
+2. Change active directory into the directory of the suragcube clone.
+3. Set active branch to "v2-release": hg checkout v2-release
+4. Run npm install in the repo dir.
+
+CAUTION: Requited dependencies change during the project lifetime and vary from branch to branch;
+you may need to run npm install again after some time, or after branch/tag change. Try to run it in
+case of strange build errors.
+
+
+The next is done in the directory where SC repo was cloned. Loop over required SugarCube versions:
+
+1. hg update --clean to clean any local changes
+2. hg checkout v2.28.2 (any tag or head here, of course)
+3. hg patch --no-commit ~/games/fc-pregmod/devNotes/sugarcube\ stuff/sugarcube-fc-changes.patch
+4. node build.js -b 2 to build release version
+5. cp dist/twine2/sugarcube-2/format.js <whenever you want>
+6. node build.js -b 2 -u -d to build debug version
+7. cp dist/twine2/sugarcube-2/format.js <whenever you want to place the debug header>