LogalDeveloper/Minecraft-Overviewer
Archived
0
Fork 0
Code Activity

integrated quickstart into installation and building pages. Wrote

Browse Source 
installation stuff.
This commit is contained in:
Andrew Brown
2011-10-01 00:41:18 -04:00
parent 499637dd31
commit ca63acf5aa
5 changed files with 228 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
building.rst
View File

@@ -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
<https://github.com/overviewer/Minecraft-Overviewer/downloads>`_ section. These
kits already contain the compiled extension and require no further setup (so you
can skip to the `Running <running.html>`_ 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 <https://github.com/overviewer/Minecraft-Overviewer/tarball/master>`_
* `Download most recent zip archive <https://github.com/overviewer/Minecraft-Overviewer/zipball/master>`_
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
<http://www.microsoft.com/express/Windows/>`_ 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 <http://fedoraproject.org/wiki/EPEL>`_. 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 <running.html>`_ 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``

31
index.rst
View File

@@ -19,21 +19,40 @@ examples, see `The Example Wiki Page <https://github.com/overviewer/Minecraft-Ov
Download
========
The Overviewer works with Linux, Mac, and Windows! We provide Windows and Debian
built executables available for download on our `Github Homepage`_.
To get your copy, head over to our `Github Homepage`_. If you are familiar with Git, you can clone the repository from there. If you would like a Debian or Windows executable, click on the Downloads link, or go `directly there <https://github.com/overviewer/Minecraft-Overviewer/downloads>`_.
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 <installing.html>`_ page.
**If you would like to build the Overviewer from source yourself (it's not that
bad)**, head to the `Building <building.html>`_ 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
<http://webchat.freenode.net/?channels=overviewer>`_. 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 <https://github.com/overviewer/Minecraft-Overviewer/issues>`_. 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

35
installing.rst Normal file
View File

@@ -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
<building.html>`_.
Windows
=======
Running Windows and don't want to compile the Overviewer? You've come to the
right place!
1. Head to the `Downloads <https://github.com/overviewer/Minecraft-Overviewer/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 <http://www.microsoft.com/downloads/en/details.aspx?FamilyID=9b2da534-3e03-4391-8a4d-074b9f2bc1bf>`_ and `VC++ 2010 <http://www.microsoft.com/downloads/en/details.aspx?familyid=a7b7a05e-6de6-4d3a-a423-37bf0912db84>`_ redistributables.
For 64 bit, you'll want these instead: `VC++ 2008 <http://www.microsoft.com/downloads/en/details.aspx?familyid=bd2a6171-e2d6-4230-b809-9a8d7548c1b6>`_ and `VC++ 2010 <http://www.microsoft.com/download/en/details.aspx?id=14632>`_
3. That's it! Proceed with instructions on `Running <running.html>`_ 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 <running.html>`_ page!

77
quickstart.rst
View File

@@ -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 <https://github.com/overviewer/Minecraft-Overviewer>`_. 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 <building.html>`_.
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 <http://www.minecraftforum.net/topic/76063-minecraft-biome-extractor-add-biome-support-to-your-mapper/page__st__140__gopid__8431028#entry8431028>`_, or `here on GitHub
<https://github.com/overviewer/minecraft-biome-extractor>`_.
.. _Minecraft Biome Extractor: http://www.minecraftforum.net/viewtopic.php?f=25&t=80902

21
running.rst
View File

@@ -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.