From 5648adbc2cbcb1d36c13e447d508864d212c6f80 Mon Sep 17 00:00:00 2001 From: TheBloke Date: Tue, 22 Dec 2015 01:39:39 +0000 Subject: [PATCH 1/5] Linux: Building docs: Some clarification on pip and sphinx-build --- docs/Compile.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index e22e99556..106a5cbc9 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -532,18 +532,26 @@ for example. To avoid doubt, ``pip`` can be used instead as detailed below. Linux ----- -Most Linux distributions will include Python as standard, including the pip -package manager. +Most Linux distributions will include Python as standard. Check your package manager to see if Sphinx 1.3.1 or later is available, but at the time of writing Ubuntu for example only has 1.2.x. -You can instead install the Python module with:: +You can instead install Sphinx with the pip package manager. This may need +to be installed from your OS package manager; this is the case on Ubuntu. +On Ubuntu/Debian, use the following to first install pip:: + + sudo apt-get install python-pip + +Once pip is available, you can then install the Python Sphinx module with:: pip install sphinx If you run this as a normal user it will install a local copy for your user only. -Run it with sudo if you want a system-wide install. Either is fine for DFHack. +Run it with sudo if you want a system-wide install. Either is fine for DFHack, +however if installing locally do check that ``sphinx-build`` is in your path. +It may be installed in a directory such as ``~/.local/bin/``, so after pip +install, find ``sphinx-build`` and ensure its directory is in your local ``$PATH``. Mac OS X From df7edaf37dcf8cac170e1ff7e821ca7b2eb4365c Mon Sep 17 00:00:00 2001 From: TheBloke Date: Tue, 22 Dec 2015 01:43:38 +0000 Subject: [PATCH 2/5] Windows: clarification on requirement of MSVC vs Visual Studio and basic explanation why --- docs/Compile.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index 106a5cbc9..18d62ea8c 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -307,7 +307,11 @@ You will need the following: Microsoft Visual Studio 2010 SP1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The free Express version is sufficient. +DFHack has to be compiled with the Microsoft Visual C++ 2010 SP1 toolchain; later +versions won't work against Dwarf Fortress due to ABI and STL incompatibilities. + +At present, the only way to obtain the MSVC 2010 C++ toolchain is to install a +full copy of Microsoft Visual Studio 2010 SP1. The free Express version is sufficient. You can grab it from `Microsoft's site `_. From 017afec271b2f44e114b5921c3224d0715eb20f9 Mon Sep 17 00:00:00 2001 From: TheBloke Date: Tue, 22 Dec 2015 01:44:49 +0000 Subject: [PATCH 3/5] Word order --- docs/Compile.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index 18d62ea8c..0140f39f5 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -310,7 +310,7 @@ Microsoft Visual Studio 2010 SP1 DFHack has to be compiled with the Microsoft Visual C++ 2010 SP1 toolchain; later versions won't work against Dwarf Fortress due to ABI and STL incompatibilities. -At present, the only way to obtain the MSVC 2010 C++ toolchain is to install a +At present, the only way to obtain the MSVC C++ 2010 toolchain is to install a full copy of Microsoft Visual Studio 2010 SP1. The free Express version is sufficient. You can grab it from `Microsoft's site `_. From 203b6b967d1e675b5caf9900dbe07278cf38a8f8 Mon Sep 17 00:00:00 2001 From: TheBloke Date: Tue, 22 Dec 2015 01:57:39 +0000 Subject: [PATCH 4/5] Windows: new section on using Bash to compile on command line under Windows --- docs/Compile.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/Compile.rst b/docs/Compile.rst index 0140f39f5..cba26daf9 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -463,6 +463,29 @@ Alternatively (or additionally), consider installing an improved Windows termina such as `Cmder `_. Easily installed through Chocolatey with: ``choco install cmder -y``. +**Note for Cygwin/msysgit users**: It is also possible to compile DFHack from a +Bash command line. This has three benefits: + +* When you've installed Git and are using its Bash, but haven't added Git to your path: + + * You can load Git's Bash and as long as it can access Perl and CMake, you can + use it for compile without adding Git to your system path. + +* When you've installed Cygwin and its SSH server: + + * You can now SSH in to your Windows install and compile from a remote terminal; + very useful if your Windows installation is a local VM on a \*nix host OS. + +* In general: you can use Bash as your compilation terminal, meaning you have a decent + sized window, scrollback, etc. + + * Whether you're accessing it locally as with Git's Bash, or remotely through + Cygwin's SSH server, this is far superior to using ``cmd.exe``. + +You don't need to do anything special to compile from Bash. As long as your PATHs +are set up correctly, you can run the same generate- and build/install/package- bat +files as detailed above. + Building/installing from the Visual Studio IDE: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After running the CMake generate script you will have a new folder called VC2010. From ce0322e8fd2bbf620ab2a9fd862be52e6161874b Mon Sep 17 00:00:00 2001 From: TheBloke Date: Tue, 22 Dec 2015 02:02:12 +0000 Subject: [PATCH 5/5] Word addition --- docs/Compile.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index cba26daf9..d8c308c81 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -464,7 +464,7 @@ such as `Cmder `_. Easily installed through Chocolatey with: ``choco install cmder -y``. **Note for Cygwin/msysgit users**: It is also possible to compile DFHack from a -Bash command line. This has three benefits: +Bash command line. This has three potential benefits: * When you've installed Git and are using its Bash, but haven't added Git to your path: