diff --git a/building.rst b/building.rst index 1cf84f2..d0d83ff 100644 --- a/building.rst +++ b/building.rst @@ -1,3 +1,150 @@ =================================== Building the Overviewer from Source =================================== + +These instructions are for building the C extension for Overviewer. Also note +that pre-built Windows and Debian executables are available in the `Downloads +`_ section. These +kits already contain the compiled extension and require no further setup (so you +can skip to the `Running `_ section of the docs). + +Get The Source +============== +First step: download the source! Either clone with Git or download the most recent snapshot + +* URL to clone: ``git://github.com/overviewer/Minecraft-Overviewer.git`` +* `Download most recent tar archive `_ + +* `Download most recent zip archive `_ + +Build Instructions For Various Operating Systems +================================================ + +.. contents:: + :local: + +Windows Build Instructions +-------------------------- + +First, you'll need a compiler. You can either use Visual Studio, or +cygwin/mingw. The free `Visual Studio Express +`_ is okay. You will want the C++ +version (Microsoft® Visual C++® 2010 Express) + +Building with Visual Studio +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Get the latest source code as per above +2. From the Start menu, navigate to the 'Microsoft Visual Studio 2010 Express' and open the 'Visual Studio Command Prompt (2010)' shortcut. +3. cd to the folder containing the Overviewer source code +4. Copy Imaging.h and ImPlatform.h from your PIL installation into the current working directory +5. First try a build:: + + c:\python26\python setup.py build + +If you encounter the following errors:: + + error: Unable to find vcvarsall.bat + +then try the following:: + + set DISTUTILS_USE_SDK=1 + set MSSdk=1 + c:\python26\python setup.py build + +If the build was successful, there should be a c_overviewer.pyd file in your current working directory. + +Building with mingw +~~~~~~~~~~~~~~~~~~~ + +1. Open a MinGW shell +2. cd to the Overviewer directory +3. Copy Imaging.h and ImPlatform.h from your PIL installation into the current working directory +4. Build:: + + python setup.py build --compiler=mingw32 + + +Linux +----- + +You will need the gcc compiler and a working build environment. On Ubuntu and +Debian, this can be done by installing the ``build-essential`` package. *For +CentOS machines, see the `CentOS`_ section below* + +You will need the following packages (at least): + +* python-imaging (for PIL) +* python-dev +* python-numpy + +Then to build:: + + python setup.py build + +OSX +--- + +1. Download the source code for PIL from http://www.pythonware.com/products/pil/ +2. Compile the PIL code (``python ./setup.py build``) +3. Install PIL (``sudo python ./setup.py install``) +4. Find the path to libImaging in the PIL source tree +5. Build Minecraft Overviewer with the path from step 3 as the value for C_INCLUDE_PATH:: + + C_INCLUDE_PATH="path from step 3" python ./setup.py build + +The following script (copied into your MCO source directory) should handle everything for you: + +.. code-block:: bash + + #!/bin/bash + + # start with a clean place to work + python ./setup.py clean + + # get PIL + if [ ! -d "`pwd`/Imaging-1.1.7/libImaging" ]; then + /usr/bin/curl -o imaging.tgz http://effbot.org/media/downloads/Imaging-1.1.7.tar.gz + tar xzf imaging.tgz + rm imaging.tgz + fi + + # build MCO + C_INCLUDE_PATH="`pwd`/Imaging-1.1.7/libImaging" python ./setup.py build + +CentOS +------ +Since CentOS has an older version of Python (2.4), there are some difficulties +in getting the Overviewer to work. Follow these steps which have been reported +to work. + +Note: commands prefixed with a "#" mean to run as root, and "$" mean to run as a +regular user. + +1. Install the `EPEL repo `_. Go to step #2 if you already have the EPEL repo installed. + + 1. ``$ wget http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm`` + 2. ``# rpm -Uhv epel-release-5-4.noarch.rpm`` + +2. Install the python26 packages and build dependancies + + 1. ``# yum groupinstall -y 'Development Tools'`` + 2. ``# yum install -y python26{,-imaging,-numpy}{,-devel}`` + +3. Install and setup Overviewer + + 1. ``$ git clone git://github.com/overviewer/Minecraft-Overviewer.git`` + 2. ``$ cd Minecraft-Overviewer`` + 3. ``$ python26 setup.py build`` + 4. Change the first line of overviewer.py from ``#!/usr/bin/env python`` to ``#!/usr/bin/env python26`` so that the Python 2.6 interpreter is used instead of the default 2.4 + +4. Run Overviewer as usual + + 1. ``$ ./overviewer.py path/to/world/ path/to/output/`` or ``$ python26 path/to/overviewer.py path/to/world/ path/to/output/`` + 2. Proceed to the `Running `_ instructions for more info. + + +Installing the Compiled Code +---------------------------- +You can run the ``overviewer.py`` script from the build directory just fine. If +you'd like to install, run ``python setup.py install`` diff --git a/index.rst b/index.rst index f6a68d0..3653e77 100644 --- a/index.rst +++ b/index.rst @@ -19,21 +19,40 @@ examples, see `The Example Wiki Page `_. +The Overviewer works with Linux, Mac, and Windows! We provide Windows and Debian +built executables for your convenience. Find them as well as the full sources on +our `Github Homepage`_. + +**If you are running Windows, Debian, or Ubuntu and would like the pre-built +packages and don't want to have to compile anything yourself**, head to the +`Installation `_ page. + +**If you would like to build the Overviewer from source yourself (it's not that +bad)**, head to the `Building `_ page. .. _Github Homepage: https://github.com/overviewer/Minecraft-Overviewer -Documentation -============= +Help +==== +**IF YOU NEED HELP COMPILING OR RUNNING THE OVERVIEWER** feel free to pop in +IRC: #overviewer on freenode. Not familiar with IRC? `Use the web client +`_. There's usually someone on +there that can help you out. + +If you think you've found a bug or other issue, file an issue on our `Issue +Tracker `_. Filing or +commenting on an issue sends a notice to our IRC channel, so the response time +is often very good! + +Documentation Contents +====================== .. toctree:: :maxdepth: 2 - quickstart building + installing running design/designdoc diff --git a/installing.rst b/installing.rst new file mode 100644 index 0000000..edc96fd --- /dev/null +++ b/installing.rst @@ -0,0 +1,35 @@ +========== +Installing +========== + +This page is for installing the pre-compiled binary versions of the Overviewer. +If you have built the Overviewer from source yourself, head back to `Building +`_. + + +Windows +======= +Running Windows and don't want to compile the Overviewer? You've come to the +right place! + +1. Head to the `Downloads `_ page and download the most recent Windows download for your architecture (32 or 64 bit). + +2. For 32 bit you may need to install the `VC++ 2008 `_ and `VC++ 2010 `_ redistributables. + + For 64 bit, you'll want these instead: `VC++ 2008 `_ and `VC++ 2010 `_ + +3. That's it! Proceed with instructions on `Running `_ the + Overviewer. + +Debian / Ubuntu +=============== +We provide an APT repository with pre-built Overviewer packages for Debian and +Ubuntu users. To do this, add the following line to your +``/etc/apt/sources.list`` + +:: + + deb http://overviewer.org/debian ./ + +Then run ``apt-get update`` and ``apt-get install minecraft-overviewer`` and +you're all set! See you at the `Running the Overviewer `_ page! diff --git a/quickstart.rst b/quickstart.rst deleted file mode 100644 index 859ff4f..0000000 --- a/quickstart.rst +++ /dev/null @@ -1,77 +0,0 @@ -================ -Quickstart Guide -================ - -This guide is aimed at new users that want to get started using Minecraft -Overviewer. It is *not* meant to explain everything, but it should help you -generate your first map. - -Getting the Overviewer -====================== - -Head to our `Github Homepage `_. You can either download the Windows package if you're running Windows, install the Debian package if you're running Debian or Ubuntu, or Git-clone the source. Building from source should be as simple as a `python setup.py build` but for more information, see `Building the Overviewer from Source `_. - -Quick-link for Git Source. (Clone this) - git://github.com/overviewer/Minecraft-Overviewer.git - -Rendering your First Map -======================== - -Overviewer is a command-line application, and so it needs to be run from the command line. If you installed Overviewer from a package manager, the command is ``overviewer.py``. If you downloaded it manually, open a terminal window and navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds, the command is ``overviewer.exe``. For other systems, it's ``./overviewer.py``. - -To generate your map, run:: - - overviewer.exe WorldName path\to\output\ # on windows, or - ./overviewer.py WorldName path/to/output/ # on other systems - -where ``WorldName`` is the name of the world you want to render, and -``path/to/output`` is the place where you want to store the rendered world. The -first render can take a while, depending on the size of your world. You can, if -you want to, provide a path to the world you want to render, instead of -providing a world name and having Overviewer auto-discover the world path. - -When the render is done, open up *index.html* using your web-browser of choice. Pretty cool, huh? You can even upload this map to a web server to share with others! Simply upload the entire folder to a web server and point your users to index.html! - -Incremental updates are just as easy, and a lot faster. If you go and change something inside your world, run the command again and Overviewer will automatically rerender only what's needed. - -Running Overviewer on a Server ------------------------------- - -There are special considerations when running Overviewer on a server. For -information on how to do this, see `Running Overviewer on a Server`_. - -.. _Running Overviewer on a Server: https://github.com/overviewer/Minecraft-Overviewer/wiki/Running-Overviewer-on-a-Server - -Extra Features -============== - -Overviewer has a lot of features beyond generating the simple map we started with. Here's information on two of them. - -Render Modes ------------- - -Overviewer supports many different rendermodes. Run `./overviewer.py --list-rendermodes` to get a list. Two of the most popular rendermodes are *lighting* and *night*, which draw shadows for the corresponding time of day. To tell Overviewer what rendermode to use, run - - ./overviewer.py --rendermodes=lighting WorldName output/dir/ - -You can also specify multiple rendermodes at once, and Overviewer will render -them all and let you toggle between them on the generated web page. To get both -*lighting* and *night* on the same page, run:: - - ./overviewer.py --rendermodes=lighting,night WorldName output/dir/ - -Biomes ------- - -Minecraft Overviewer has support for using the biome info from the `Minecraft -Biome Extractor`_. If you run the biome extractor on your world, during the -next run Overviewer will automatically recognize the biome info and use it to -colorize your grass and leaves appropriately. This will only appear on updated -chunks, though; to colorize the entire world you will need to rerender from -scratch by deleting the old render. - -**Note**: as of Minecraft 1.8, you currently need to use a patched Biome -Extractor that can be found `here `_, or `here on GitHub -`_. - -.. _Minecraft Biome Extractor: http://www.minecraftforum.net/viewtopic.php?f=25&t=80902 diff --git a/running.rst b/running.rst index 378f042..70a400f 100644 --- a/running.rst +++ b/running.rst @@ -1,3 +1,24 @@ ====================== Running the Overviewer ====================== + +Rendering your First Map +======================== + +Overviewer is a command-line application, and so it needs to be run from the command line. If you installed Overviewer from a package manager, the command is ``overviewer.py``. If you downloaded it manually, open a terminal window and navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds, the command is ``overviewer.exe``. For other systems, it's ``./overviewer.py``. + +To generate your map, run:: + + overviewer.exe WorldName path\to\output\ # on windows, or + ./overviewer.py WorldName path/to/output/ # on other systems + +where ``WorldName`` is the name of the world you want to render, and +``path/to/output`` is the place where you want to store the rendered world. The +first render can take a while, depending on the size of your world. You can, if +you want to, provide a path to the world you want to render, instead of +providing a world name and having Overviewer auto-discover the world path. + +When the render is done, open up *index.html* using your web-browser of choice. Pretty cool, huh? You can even upload this map to a web server to share with others! Simply upload the entire folder to a web server and point your users to index.html! + +Incremental updates are just as easy, and a lot faster. If you go and change something inside your world, run the command again and Overviewer will automatically rerender only what's needed. +