From 193e71793a3a0bf3e72b936a65059eec17c3f669 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 16:58:58 +1100 Subject: [PATCH] Fix compile, intro, scripts - script-syntax.py now exits with 1 instead of silently catching the error if lua or ruby are missing - index paths are absolute (from the repo root) - less strong suggestion for third-party packs - re-added lua-example and test-perlin doc - corrected and clarified Compile some more --- docs/Compile.rst | 69 +++++++++++++++-------------------- docs/Introduction.rst | 6 +-- index.rst | 26 ++++++------- scripts/devel/lua-example.lua | 14 +++++++ scripts/devel/test-perlin.lua | 2 - travis/script-syntax.py | 6 +-- 6 files changed, 62 insertions(+), 61 deletions(-) create mode 100644 scripts/devel/lua-example.lua diff --git a/docs/Compile.rst b/docs/Compile.rst index 4a72f0dc4..752b9b5fd 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -14,17 +14,8 @@ and `install the latest release instead `. How to get the code =================== DFHack doesn't have any kind of system of code snapshots in place, so you will have to -get code from the github repository using git. -The code resides at https://github.com/DFHack/dfhack - -On Linux and OS X, having a ``git`` package installed is the minimal requirement (see below for OS X instructions), -but some sort of git gui or git integration for your favorite text editor/IDE will certainly help. - -On Windows, you will need some sort of Windows port of git, or a GUI. Some examples: - - * http://msysgit.github.io - this is a command line version of git for windows. - Most tutorials on git usage will apply. - * http://code.google.com/p/tortoisegit - this puts a pretty, graphical face on top of msysgit +get code from the github repository using git. How to get git is described under +the instructions for each platform. To get the code:: @@ -34,16 +25,14 @@ To get the code:: If your version of git does not support the ``--recursive`` flag, you will need to omit it and run ``git submodule update --init`` after entering the dfhack directory. -If you want to get really involved with the development, create an account on +If you want to get involved with the development, create an account on Github, make a clone there and then use that as your remote repository instead. -Detailed instructions are beyond the scope of this document. If you need help, -join us on IRC (#dfhack channel on freenode). +We'd love that; join us on IRC (#dfhack channel on freenode) if you need help. Build types =========== -``cmake`` allows you to pick a build type by changing the -``CMAKE_BUILD_TYPE`` environment variable:: +``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable:: cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE @@ -62,23 +51,25 @@ Dependencies ------------ DFHack is meant to be installed into an existing DF folder, so get one ready. -For building, you need a 32-bit version of GCC. For example, to build DFHack on -a 64-bit distribution like Arch, you'll need the multilib development tools and libraries. -Alternatively, you might be able to use ``lxc`` to +We assume that any Linux platform will have ``git`` available. + +To build DFHack you need a 32-bit version of GCC. On 64-bit distributions +(which is most of them), this means you'll need the multilib development tools +and libraries. Alternatively, you might be able to use ``lxc`` to :forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Before you can build anything, you'll also need ``cmake``. It is advisable to also get ``ccmake`` on distributions that split the cmake package into multiple parts. You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts). -You should be able to find them in your distro repositories (on Arch linux -``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``. +You should be able to find them in your distro repositories. -To build Stonesense, you'll also need OpenGL headers. +* On Arch linux, ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``) +* On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. +* On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. +* Debian-derived distros should have similar requirements. -On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. -On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. -Debian-derived distros should have similar requirements. +To build Stonesense, you'll also need OpenGL headers. Build @@ -100,14 +91,12 @@ Alternatively, you can use ccmake instead of cmake:: make install This will show a curses-based interface that lets you set all of the -extra options. +extra options. You can also use a cmake-friendly IDE like KDevelop 4 +or the cmake-gui program. -You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui -program. - -The libstdc++ version bug -~~~~~~~~~~~~~~~~~~~~~~~~~ +Incompatible libstdc++ +~~~~~~~~~~~~~~~~~~~~~~ When compiling dfhack yourself, it builds against your system libc. When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions. @@ -116,14 +105,12 @@ This manifests itself with the error message:: ./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version `GLIBCXX_3.4.15' not found (required by ./hack/libdfhack.so) -To fix this, simply remove the libstdc++ shipped with DF, it will fall back -to your system lib and everything will work fine:: +To fix this, you can compile DFHack with GCC 4.5 - or simply remove the +libstdc++ shipped with DF, and it will fall back to your system lib:: cd /path/to/DF/ rm libs/libstdc++.so.6 -Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5. - Mac OS X ======== @@ -201,16 +188,18 @@ On Windows, DFHack replaces the SDL library distributed with DF. Dependencies ------------ -First, you need ``cmake``. Get the win32 installer version from -`the official site `_. +You will need some sort of Windows port of git, or a GUI. Some examples: +* `Git for Windows `_ (command-line and GUI) +* `tortoisegit `_ (GUI and File Explorer integration) + +You need ``cmake``. Get the win32 installer version from +`the official site `_. It has the usual installer wizard. Make sure you let it add its binary folder to your binary search PATH so the tool can be later run from anywhere. You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient. -Grab it from Microsoft's site. - -You'll also need the Visual Studio 2010 SP1 update. +Grab it from Microsoft's site. You'll also need the Visual Studio 2010 SP1 update. For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT. `Strawberry Perl `_ works nicely for this. diff --git a/docs/Introduction.rst b/docs/Introduction.rst index f0fc0a0bf..8a82e0f10 100644 --- a/docs/Introduction.rst +++ b/docs/Introduction.rst @@ -37,9 +37,6 @@ allows easier development of new tools. As an open-source project under Installing DFHack ================= -New players are encouraged to :wiki:`get a pack with DFHack preinstalled -`. - DFHack is available for the SDL version of Dwarf Frtress on Windows, any modern Linux distribution, and OS X (10.6.8 to 10.9). It is possible to use Windows DF+DFHack under Wine on Linux or OS X. @@ -60,6 +57,9 @@ Uninstalling is basically the same, in reverse: * On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. * On Linux or OSX, remove the DFHack files. +New players may wish to :wiki:`get a pack ` +with DFHack preinstalled. + Getting started =============== diff --git a/index.rst b/index.rst index 7f3e815a3..de587e95a 100644 --- a/index.rst +++ b/index.rst @@ -36,10 +36,10 @@ User Manual .. toctree:: :maxdepth: 2 - docs/Introduction - docs/Core - docs/Plugins - docs/Scripts + /docs/Introduction + /docs/Core + /docs/Plugins + /docs/Scripts Other Contents ============== @@ -47,9 +47,9 @@ Other Contents .. toctree:: :maxdepth: 1 - docs/Authors - LICENSE - NEWS + /docs/Authors + /LICENSE + /NEWS For Developers ============== @@ -57,9 +57,9 @@ For Developers .. toctree:: :maxdepth: 1 - docs/Contributing - docs/Compile - docs/Lua API - library/xml/SYNTAX - library/xml/how-to-update - docs/Binpatches + /docs/Contributing + /docs/Compile + /docs/Lua API + /library/xml/SYNTAX + /library/xml/how-to-update + /docs/Binpatches diff --git a/scripts/devel/lua-example.lua b/scripts/devel/lua-example.lua new file mode 100644 index 000000000..bbdb04ed6 --- /dev/null +++ b/scripts/devel/lua-example.lua @@ -0,0 +1,14 @@ +-- Example of a lua script. +--[[=begin + +devel/lua-example +================= +An example lua script, which reports the number of times it has +been called. Useful for testing environment persistence. + +=end]] + +run_count = (run_count or 0) + 1 + +print('Arguments: ',...) +print('Command called '..run_count..' times.') diff --git a/scripts/devel/test-perlin.lua b/scripts/devel/test-perlin.lua index 2759d7085..3b3a6a11a 100644 --- a/scripts/devel/test-perlin.lua +++ b/scripts/devel/test-perlin.lua @@ -5,8 +5,6 @@ devel/test-perlin ================= Generates an image using multiple octaves of perlin noise. -Used by `3dveins`? - =end]] local args = {...} diff --git a/travis/script-syntax.py b/travis/script-syntax.py index 0b977f59d..c4454d7be 100644 --- a/travis/script-syntax.py +++ b/travis/script-syntax.py @@ -24,9 +24,9 @@ def main(): except subprocess.CalledProcessError: err = True except IOError: - # catch error if not in Travis and Lua/Ruby is not available - if os.environ.get('TRAVIS', False): - raise + if not err: + print('Warning: cannot check %s script syntax' % args.ext) + err = True sys.exit(int(err))