LINUX_INSTALL.txt

LINUX INSTALL NOTES [LINUX_INSTALL.txt]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


FOREWORD
~~~~~~~~

This installer is still in development stage, but it has been tested on
Mint 18, OpenSuSE 13.2 and Ubuntu 14.04.

Ensure your package manager sources, repositories and caches are up to date.

Tests could not be performed on other Linux flavor yet, but this
installer is similar to the former one, and shall work on the above systems.

The binary libaries for Pocket Edition, PNG and NBT support are included
in this distribution. They have been successfully tested on the above
systems.

Please, read carefully this document, especially the PREREQUISITES and
DEPENDENCIES sections. I know it's boring to read (and you can believe
me, it's boring to write), but it is not possible to make a 'click'n
play' single Linux all platforms installer for now...

Each system is different. You may have to adapt to make MCEdit run on
your system.

If you have trouble with the graphical version of this installer, open
a console, go to the 'mcedit' folder generated by the .run file you
downloaded and enter `sh install.sh -t`.

MCEdit will be installed for the current user only. The other users of
the computer won't be able to run it properly.
The installer try to install as much as possible dependencies in a
virtual environment installed for MCEdit in the '.venv' directory.
If a dependency is found on the system and is the required version, it is
not installed.

Interesting tricks can be found in the OPENSUSE TRICKS, POCKET EDITION
SUPPORT COMPILATION and NBT SUPPORT sections.

A log file `MCEdit-<version>-install.log` is created by the installer.
It can be found in (sorted by preference):
* `~/.local/log`
* The directory where you launched the installer.
* The directory defined by the environment variable `temp` or `TEMP` or
  `tmp` or `TMP`, if any.
* `/tmp`.

If none of these places are accessible and writable, no log will be created...

For any support, you can go to:

https://github.com/Khroki/MCEdit-Unified

and

https://www.reddit.com/r/MCEdit

-- D.C.-G. (LaChal)


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COMMAND-LINE ARGUMENTS
~~~~~~~~~~~~~~~~~~~~~~

These command line arguments are very experimental.
They have been tested, but may have a strange behaviour.

The installer accepts command-line arguments:

-d --destination <path>  Destination path to move %{prog_name} to.
                         The path must exists and be writable.
   --force-build <name>  Force build an internal library. Can be specified
                         several Times. See documentation for details.
                         Overrides --no-build. Build <name> even if --no-tests
                         is given.
-h --help                Print this text and exit.
   --no-build            Don't build the internal libraries.
   --no-checks           Don't check the dependencies.
                         Implies '--no-deps'.
   --no-cleanup          Don't clean dowloaded dependencies sources and
                         utilities.
   --no-deps             Don't install dependencies.
   --no-desktop-launcher Don't create a launcher on the desktop.
   --no-launchers        Don't create the launchers.
   --no-menu-launcher    Don't create a launcher in the menu.
   --no-shell-launcher   Don't create a shell command 'mcedit'.
   --no-tests            Don't perform tests.
-r --response <file>     Use the specified file to read command-line
                         arguments.
                         One argument a line.
                         The arguments must have the same syntax as on the
                         command-line (including the hyphens).
-s --silent              Don't show or ask anything to the user.
                         To be used with '--yes' or '--response'.
-t --text                Use text mode.
-v --verbose [level]     Write more information to the log file.
                         If [level] is given, it must be a number; it
                         defaults to '1'.
-y --yes                 Answer 'yes' to all questions.

Note that, when the '--yes' switch is given, the NBT, PNG and Pocket
Edition binary supports are automatically re-built.

'--no-deps' will not install the dependencies, even some are missing
or are not the right version, but the dependencies checks will be run.
You can expect that MCEdit will not work if the dependencies are not
satisfied.

'--no-checks' will not perform dependencies checks, nor dependencies
installation.
Use this if you're sure they are met.

'--no-tests' is used to bypass the NBT, PNG and PE internal supports.

'--no-build' will not make the installer try to rebuild the internal
supports for NBT, PNG and Pocket Edition.
The tests for these libraries will be run.

'--silent' the installer will not output anything to the user, but you
will see output from the packager (the .run you downloaded) and maybe
from the building tools included in the installer.

'--destination' must have a parameter. It will be used to move MCEdit
to the specified place.

The 'no launcher' switches are used to skip all or specific launcher
creation.

'--response' can be used to give a file containing switches and
arguments.
As said above, a line will contain a command-line argument or switch.
This file can also contain blanks lines and comments (lines starting
with '#')
Example:
```
# MCEdit response file example

# The next line will intall the program in '/foo/bar/baz' directory
# provided it exists.
--destination /foo/bar/baz

# The next line disables questions, but the output is not.
--yes
# No blank line to tell no launcher will be created in the menu.
--no-menu-launcher
```

'--text' will force the installer to run in pure text mode, even if the
'dialog' utility is installed on your system. You'll have to type in the
shell the answers to all the questions you'll be asked.

'--help' eh...


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SETUP SCRIPTS
~~~~~~~~~~~~~

To build the internal binary supports, two Python setup scripts are used.

For the NBT and PNG supports, `setup.py` in MCEdit install directory is used.
Entering `python setup.py help` in a shell opened in MCEdit directory will
output notes about its usage.

For the PE support, the `setup_leveldb.py` script is used.
See the POCKET EDITION LIBRARIES section below.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PEREQUIQISITES
~~~~~~~~~~~~~~

You may have root permissions on your system to install the items listed
here.

Note that the installer will try to 'install' some system packages only
for the MCEdit installation process and usage. No root elevation is required,
and your system won't be changed.

Binaries
--------

You must have these binaries installed on you system to run the
installer.

* gcc (*)
* g++
* make (*)
* tar (*)
* unzip (*)
* pip (See Python section below)

(*) Shall be present on any decent Linux system.


Python
------

* Python 2.7.3 or higher.
* pip for Python 2.7, which provides easy_install-2.7.
  The installer shall be able to install it for the current user.


Libraries
---------

To properly run MCEdit-unified, you need to have:
* xclip
  OR
* gtk package

Installing xclip may be the simpliest way.
(Kubuntu 15.10 and Ubuntu 16.04 with KDE desktop seem not having xclip
library installed by default.)


You also need the development packages for these ones. See Development
section below.

* pygame (python-pygame)
    The required version is 1.9.1, but MCEdit may work with another
    version, let us know!
    If you want to let the installer build pygame (which can fail),
    you'll need these libraries and their 'dev' packages:

    - libSDL-1_2-0
    - libSDL-devel
    - libSDL_gfx13
    - libSDL_image-1_2-0
    - libSDL_mixer
    - libSDL_ttf-2_0-0
    - libpng16
    - libjpeg8
    - libsmpeg
    - libv4l1

    By the way, you'll install them with root permissions, so you may
    prefer to install pygame with the package manager...
    But, if these dependencies are already installed on your system, the
    installer will install pygame itself.
    Note that, depending your system this list may not be complete.


Development
-----------

* libc6-dev

* python-dev for Python 2.7 is needed only if the compilation of one
  of the dependencies fails.

* Cython 0.21.1 or higher is needed to compile the NBT and PNG supports,
  however this installer will download it only to build them.


The following libraries are needed to install pygame:

* libsdl-image1.2-dev
* libsdl-mixer1.2-dev
* libsdl-ttf2.0-dev
* libsdl1.2-dev
* libsmpeg-dev
* libportmidi-dev
* libswscale-dev
* libavformat-dev
* libavcodec-dev
* libv4l-dev


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEPENDENCIES
~~~~~~~~~~~~

Here are listed the Python 2.7 dependencies. They shall be all installed
for the user only by the installer if they are not found on your system
or have a non-compliant version.

* ftputil 3.2 or over
* numpy 1.8.1 or over
* pillow 1.7.8 to 2.6.1 (*)
* pygame 1.9.1 (*)(**)
* PyOpenGL 3.0.1 to 3.1.0
* python-xlib 0.14 or over
* Xlib 0.14

(*)    You may need the Python headers for your distribution installed
       order to install this library.
(**)   Provided you have the prerequisites installed.

The installer shall be able to install all these Python packages.

If the installation of some dependencies fail, you will have to install
them with your package manager.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OPENSUSE TRICKS
~~~~~~~~~~~~~~~

AkiraTakizawa could not run MCEdit after the installation.
He choosed to install the dependencies system wide.

Here is a summary of what AkiraTakizawa did to make it work.
The discussion can be found there:
https://github.com/Khroki/MCEdit-Unified/issues/346 and
what follows in this chapter is mostly copied from his posts.
Many thanks to him!


Library `ftputil`
-----------------

If you have an error saying 'ImportError: No module named error' when
you run MCEdit, and the error text contains references to `ftputil` or
`ftp_client`, that means the library installed by the installer isn't
recognized by Python.
The already present version (and uncompatible with MCEdit) is used.
Look at the `ftputil` and `python_ftputil` packages present on your
system, and uninstall them all.

Then:
* Download ftputil-3.2-1.tar;
* Turn it into an rpm package with the command python
  `setup.py bdist_rpm`.
  Packing ftputil 3.2 requires a little modification. For some reason it
  can't see the file VERSION right under its nose. I forced it by
  changing line 19 in setup.py:
  Change `_version = open("VERSION").read().strip()` into 
  `_version = "3.2"` and it's good to go.
* Install it.

Delete MCEdit and run the installer. Now `ftputil` version is the good
one, and it will work.


Library `Xlib`
--------------

If you experience issues with the Python package `Xlib`, just get the
noarch RPM for python-xlib 0.14 and install it.

You may have to remove and reinstall MCEdit.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
POCKET EDITION LIBRARIES
~~~~~~~~~~~~~~~~~~~~~~~~

There is a dynamic library involved in the PE support: libleveldb.so.

It is embedded in the installer and shal work, provided you have zlib
library installed on your system.

If the Pocket Edition do not work, or the tests failed, see the
`INSTALL_LEVELDB` file in the `pymclevel` directory.

Note that, the installer provides the ability to rebuild the PE support if
tests fails.
However, it may not work, depending on your system.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NBT SUPPORT
~~~~~~~~~~~

MCEdit-Unified uses it own internal NBT format support.

It was in the prehistorical era of MCEdit an external project.

There are two form of the NBT support in MCEdit-unified: a pure Python
one and a binary one.

When MCEdit starts, it try to load the binary support, and if it is not
found, fall back to the pure Python one.

The binary is included in the installer.

It works on 64bit Ubuntu 12.10 and 14.04.2, opeSUSE 13.2 and Mint 17 and 18.

If you notice bugs, slowness (more than with the pure Python support)
or you're not happy with the binary support you may want to recompile
it.

To recompile, you'll need to install Cython 0.21.1 or higher and run
`python setup.py nbt` MCEdit install directory.
Be sure to have the Python headers on your system (python-dev) before
building NBT support.

You can also use the pure Python library by deleting the '_nbt.so' file
which lies in your MCEdit install 'pymclevel' directory.

When MCEdit is installed with the installer, the NBT binary is tested.
Some test failures aren't critical and won't crash MCEdit. (Don't worry
about the speed test failure, it won't prevent the binary to work.)
If you experience issues with a '_nbt.so' file when running MCEdit, you
can delete it from the 'pymclevel' directory in your MCEdit install.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PNG SUPPORT
~~~~~~~~~~~

A binary PNG support will be built during the installation.
As for the NBT one, it is not critical if it fails. The oure Python interface
will take over.

As for the NBT support, Cython and the Python headers are needed to compile it.

The installer compiles it, but if you need to recompile, enter the following
command in a shell you opened in the MCEdit install directory:
`python setup.py png`