Set up a Development Environment

Contributing code to the Freeciv21 project or contributing to any of the games that the Longturn community manages requires a bit of setup. This document should get you up and running with the basics. It should be noted, that you typically only have to go through this process once unless you setup a new workstation.

Workstation

Freeciv21 can be developed on Linux, Windows, and macOS. Any current version of these OS’s is acceptable. For Windows, you will need to setup either the MSYS2 environment or Visual Studio to do development. Refer to Setting up MSYS2 for Windows or Visual Studio for more information. It should be generally understood that Linux is the preferred development platform. For a complete set of installation steps, you can refer to Compiling Freeciv21.

Technically all you need is a text editor of some kind to edit the files, but most people prefer to use an integrated development environment (IDE).

All platforms can use KDevelop. However, there are some caveats:

On Windows, due to the nature of the integration with MSYS2, native compilation and debugging is not supported. This is resolved with Visual Studio as the IDE.
On macOS, KDevelop is still considered experimental. Many Mac users use XCode.

For the best results, especially if you are editing game code and not just Longturn game rulesets or documentation, you will want Linux to be your workstation OS. Many of the current developers use a Debian variant such as Ubuntu. Instructions for getting all of the tools needed for Debian Linux can be found in Compiling Freeciv21. Do not follow the steps to clone the repository (e.g. the git clone command), that will happen in a bit.

GitHub

The Longturn Community uses the online source code control and revision system known as GitHub. To contribute, you will need an account on this platform. There is no cost.

With an account, you can go to the Longturn community repository page and fork a repository (such as the Freeciv21 repository) to your personal GitHub account. Go to the main page of the repository you want to fork and you will find a fork button in the upper-right corner.

In order to get code pushed to the forked repository to your local workstation, you need to setup an SSH key pair to share with GitHub. Follow these instructions.

With SSH set up, now it is time to clone the forked repository from your personal GitHub account to a local copy on your workstation.

First make a working directory to place the files in:

$ mkdir -p $HOME/GitHub

$ cd $HOME/GitHub

You can get the appropriate path by going to your forked copy in a browser, click the code button and then select the SSH option as shown in this sample screenshot:

Once you have the proper path, here is the command to clone the repository:

~/GitHub$ git clone git@github.com:[username]/freeciv21.git

This will clone the forked repository to the ~/GitHub/freeciv21 directory on your computer.

The final repository setup item is to link the original Longturn project repository to your local area on your computer:

~/GitHub/freeciv21$ git remote add upstream https://github.com/longturn/freeciv21.git

You will also need to set a couple global configuration settings so git knows a bit more about you.

~/GitHub/freeciv21$ git config --global user.email [email address associated with GitHub]
~/GitHub/freeciv21$ git config --global user.name [your first and last name]

KDevelop Project Setup

On Linux, the easiest way to install KDevelop is with a command such as this:

$ sudo apt install kdevelop clang-format-11

Once installed, you can then import the Freeciv21 project into it. Follow these steps:

Open Kdevelop
Project ‣ Open/Import Project
Find freeciv21/CMakeLists.txt
Session ‣ Rename Current Session to Freeciv21
Project ‣ Open Configuration ‣ Language Support. Click on the Language Support tab and ensure that the C++ Profile is c++17, the C Profile is c99, the OpenCL C Profile is CL1.1, the CUDA C Profile is c++11, and finall the Compiler for Path is GCC.
Allow kdevelop to parse all of the code. This can take a while. Eventually you will see a full tree of the code in the Projects tab on the left.

Here are some useful help/documentation links:

Now you are ready to edit some code! When ready, follow the steps to submit a pull request here: How to Submit a Pull Request.

Qt Creator

Freeciv21 uses the Qt framework for many things, especially the game client. There are many .ui files in the client directory. If you want to edit those in a user interface (versus editing the raw XML), you will want to install Qt Creator. You do so with a command such as this:

$ sudo apt install qtcreator

Once installed you will get access to a program called Qt Designer. This tool is a graphical interface you can use to edit the .ui files. You also gain access to Qt documentation inside of KDevelop as well. You can read the Qt Designer Manual for more help here: https://doc.qt.io/qt-5/qtdesigner-manual.html