Contributing to Tiled

If you already know a bit of C++, contributing to the Qt version of Tiled is not hard! All you need to do is learn how to use the Git version control system and the Qt application framework. But you can do either as you go along.

Checking Out the Source Using Git

Install Git

Installing Git is going to be a bit different depending on your operating system. If you go to the Git download page, you should be able to find the appropriate link.

Checking out Tiled

While you can use the Git gui to check out the repository, I'm only going to show you the way of the command line here. The Git repository is located here on github.com. You'll find Tiled at http://github.com/bjorn/tiled.

To make a local copy of this repository, use the command advertised there:

$ git clone git://github.com/bjorn/tiled.git
$ cd tiled
$ git log

As the last command shows, this not only gives you a local copy of the source code, but also includes all the development history, allowing you to browse the history quickly and find out what happened until now.

Getting Started with Development

Install a C++ compiler

• On Linux, make sure g++ is installed.
• On Windows, I'd recommend getting the Qt package that includes MinGW (available since Qt 5.0.1).
• On MacOS X, I believe you need to install Xcode.

Install Qt and zlib

Get Qt from http://qt-project.org/downloads. The default package ships with Qt Creator, which provides an easy way to compile & run Tiled, as well as being a powerful IDE for making changes to Tiled.

Tiled also depends directly on zlib for supporting compression. On Debian and Ubuntu, zlib can be installed as follows:

$ sudo apt-get install zlib1g-dev

On Windows, install the "Complete package" of Zlib for Windows. If you don't install it to the default location in Program Files, set the ZLIB_PATH environment variable to the installation directory you picked.

Compile and Run

Once you have everything installed, you should be able to just open tiled.pro in Qt Creator. If Qt Creator did not auto-detect your Qt libraries, set those up in the preferences (under Build & Run -> Qt Versions, and then set up a Kit for it and add this kit in the 'Projects' mode). Then, make sure the run target is set to 'tiled' and not one of the other applications shipping with Tiled. Finally you can press the Run button to have it compile and run the application.

If you prefer to stick with the command line, you'll find that you can compile and run Tiled using the following commands:

$ qmake        # Generate the Makefiles
$ make         # Compile Tiled
$ bin/tiled    # Run Tiled

Note that on some systems the qmake command is not available (or may default to Qt 3, which Tiled does not compile against). In that case, use qmake-qt4, qmake-qt5 or whatever else is appropriate for your system.

Building Tiled with the Qt Creator and Qt 5.0.1 with MinGW on Windows systems

Since the libraries and the structure of Qt have changed with the new release there are some more dependencies to be resolved. Once Tiled is being run out of Qt Creator it will work out of the box, but if you try to run it by directly invoking the executable errors will pop up. You have to copy and paste the following dll files from the QT_DIR\5.0.1\mingw47_32\bin directory into the root directory where the executable can be found:

• icudt49.dll
• icuin49.dll
• icuuc49.dll
• libEGL.dll
• libgcc_s_sjlj-1.dll
• libGLESv2.dll
• libstdc++-6.dll
• libwinpthread-1.dll
• Qt5Core.dll
• Qt5Gui.dll
• Qt5OpenGL.dll
• Qt5Widgets.dll

To use the delay-loaded dlls you have to copy the files from QT_DIR\5.0.1\mingw47_32\plugins\imageformats to plugins\imageformats. It is recommended to include all files without the d suffix that is using qjpeg.dll and not qjpegd.dll.

Since Qt 5 you have to copy qminimal.dll and qwindows.dll from QT_DIR\5.0.1\mingw47_32\plugins\platforms to plugins\platforms. The last file to be created is qt.conf in the root directory with the following contents

[Paths]
Plugins = plugins
Translations = translations

Contributing Patches

Edit Code and Commit

Edit the code using your favourite editor. While you're at it, always feel free to ask questions on the mailing list or on the IRC channel, see the relevant links on the website.

Once you think your change is ready, you need to create a commit. Before you create your first commit, you should tell Git who you are. You can do so as follows:

$ git config --global user.name "Real Name Surname"
$ git config --global user.email "your.email@domain"

This information is stored with each commit you make, and makes sure we all know who the author of the change was later on. Note that Git does not have a concept of user accounts, as is common in centralized version control systems like Subversion.

Now, before you commit, it is generally a good idea to look at the output of git status. This might look something like this:

[bjorn@thor tiled-qt]$ git status
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   src/mapscene.cpp
#	modified:   src/src.pro
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	src/smartbrush.cpp
#	src/smartbrush.h

Here, Git says that you have modified the files mapscene.cpp and src.pro, and introduced two new files unknown to git (smartbrush.cpp and smartbrush.h). To commit these changes, you would do:

$ git add src/mapscene.cpp
$ git add src/src.pro
$ git add src/smartbrush.cpp
$ git add src/smartbrush.h
$ git commit
[write commit message in editor that was started]

Note that in this case, you could also have done this instead of adding all files individually:

$ git add -A

However, this is a bit dangerous, since it adds all files unknown to git, which may include files you don't want to add to version control. Read the output of git status carefully before doing something like that. A safer way would have been:

$ git add src/smartbrush.{cpp,h}
$ git commit -a

Here, the second line tells Git to add all changes to already tracked files to the commit. I find the easiest way to create a commit, however, to be git gui. This allows you to interactively select the parts you want to be part of your commit, review those changes before you commit, and to write your commit message.

Feeding Your Change Back Upstream

There's many ways to do this. If you are unsure about your change, have somebody review it. Export your commits using:

$ git format-patch origin/master

Then, send the file to the mailing list or show it to somebody on IRC. If you want to contribute to the project longer term, you may prefer to create a fork of the Tiled repository on github.com, and push changes there. That allows you to do "pull requests" via the website, and it allows everybody to see what you are changing in Tiled in general.

When your patch is good for inclusion, it will be pushed to the main repository. When updating your local repository, make sure your local changes are rebased on top of the remote ones, by pulling as follows:

$ git pull --rebase

This ensures that accepted commits are dropped, and no unnecessary merge commits are created for commits which haven't been accepted yet.

Happy coding!