FlightGear Git on Windows

From FlightGear wiki
Jump to navigation Jump to search

This document guides you through the installation process of the development version of FlightGear (Git) on Windows.

A first Git install

Pre-installation work

Before we start, we will choose an installation directory. This can be any drive on your computer. In this document, we assume that you install FlightGear on the D:/ drive. Just replace the commands given in this document by your installation directory when using another drive or different directory root.

Create the following directories on your drive:

  • FlightGear/
    • bin/
      • win32/
    • data/

Obtaining data from Git

You can use any Git software, however we advise to use msysGit (which will be used in this document). You can download it through this link. Follow the download/installation instructions that show up on your screen.

If you have a slow internet connection or you cannot keep your computer on for the long time that it takes for the data to download from the git server, follow Method 2.

Method 1:

Before starting, confirm that the address you're using DOES NOT contain an existing copy of FlightGear!

The Git Bash window

Open Git Bash via C:/Program Files/msysgit/Git Bash (or open via the shortcut) and run (replacing the path with your prefered path):

cd D:/FlightGear/data

In the event that the program refuses to read the file, try this instead:

cd "D:/FlightGear/data"

(replace the above addresses with wherever your fg/data folder should be -make sure the file doesn't exist, though!)

Then run the following, to initialise a Git repository. This should create a .git directory in data/.

git init

Add the following command and press Enter.

git clone git://gitorious.org/fg/fgdata.git

Now msysGit will pull the entire fgdata package into your FlightGear/data directory. This can take up to a couple of hours on slow internet connections!

IMPORTANT: Be sure you use msysGit 1.7.0.2 or newer version, as previous versions have problems with large repositories, and won't download more than 2Gb of data.

IMPORTANT II: Some files demand that CR/LF (carriage return / line feed) line breaks are kept in the way they are stored on Gitorious. Make sure to set "git-config core.safecrlf true" and "git-config core.autocrlf false" in your options or you may receive nasty error or even a crash on startup of FG (e.g. fgtzfile_read(): : Invalid argument... Fatal error: Timezone reading failed).

Method 2:

Download the fgdata.bundle from http://peter-server.homelinux.net/fgdata/fgdata/ or http://flightgear.mxchange.org/pub/fgfs/. Use Right mouseclick > Save target as on the file, if you end up with a webpage full of weird characters.

After downloading, verify that the file is not corrupted using this MD5 checksum:

2996221BD2B8AB7740F332F49396CF56

You can verify the checksum of your file using any free Md5 checking utility available on the internet like this one : http://www.bullzip.com/products/md5/info.php It should match to the one given above. If not, redownload.

Copy this file to your FlightGear/data directory.

Open Git Bash via C:/Program Files/msysgit/Git Bash (the shortcut) and run (replacing the path with your prefered path):

cd FlightGear/data
git clone fgdata.bundle

Now msysGit will pull the entire fgdata package into your FlightGear/data directory. Wait for a few minutes until it is completed (the flashing cursor will reappear after it is done).

If your get this error:

warning: unrecognized header: -deg" - /orientation/roll += "-deg" - /position/altitude += "-ft" - /position/altitude-agl += "-ft" - /position/latitude += "-deg" - /position/longitude += "-deg" - /radios   
/adf/frequencies/selected += "-khz" - /radios/adf/frequencies/standby += "-khz" - /radios/adf/rotation += "-deg" - /radios/nav1/* => /radios/nav[0]/* - /radios/nav2/* => /radios/nav[1]/* - /radios/nav[*]
/dme/distance += "-nm" - /radios/nav[*]/frequencies/selected += "-mhz" - /radios/nav[*]/frequencies/standby += "-mhz" - /radios/nav[*]/radials/actual += "-deg" - /radios/nav[*]/radials/selected += "-deg" - 
/sim/view/goal-offset += "-deg" - /sim/view/offset += "-deg" - /steam/adf += "-deg" - /steam/airspeed += "-kt" - /steam/altitude += "-ft" - /steam/gyro-compass += "-deg" - /steam/gyro-compass-error += "-deg" - 
/steam/mag-compass += "-deg" - /steam/vertical-speed += "-fpm" - /velocities/airspeed += "-kt" - /velocities/side-slip += "-rad" - /velocities/speed-down += "-fps" - /velocities/speed-east += "-fps" - 
/velocities/speed-north += "-fp 
warning: remote HEAD refers to nonexistent ref, unable to checkout.

run this command:

cd fgdata

and press enter then

git checkout -b master origin/master

It should be fixed now.


Now pull from GIT to update to the latest files using

git pull git://gitorious.org/fg/fgdata.git master

Getting the binary

Now we've got all the data, we need to have a binary, which contains the actual software that runs FlightGear.

  • Go to http://flightgear.simpits.org:8080/job/Win32-installer-Cmake/ and download the fgfs_win32_nightly_*.exe file. Run the installer and follow its instructions. Let it install the binary into your FlightGear/bin/win32 directory.
  • If you want to automate this, you can run the installer in silent mode by passing the /S parameter, the /D parameter can be used to set the target directory into which he needs to install the binaries:
    • e.g. fgfs_win32_vs2010_nightly_2.7.0.exe /S /D=C:\Flightgear\bin\win32


If your antivirus warns you of a trojan, ignore. AVG and avast! are known for false positives.

Running FlightGear

Run FlightGear/bin/win32/fgrun.exe to launch the FlightGear Wizard, or run FlightGear/bin/win32/fgfs.exe by commandline.

Keeping your FlightGear up to date

Of course you want to keep FlightGear up to date, to keep current with the latest developments. Else you don't have a reason to use the development version.

  1. Download the latest binary, as described in Getting the binary and overwrite the old one in FlightGear/bin/win32 (instead you could rename the current binary's directory to something like win32_latest, in case the newer binary doesn't work well).
  2. Update your FlightGear/data/ directory, to match it with the binary. For smooth operations, it is very important to have data and a binary from matching dates!
    1. Navigate to FlightGear/data/ directory and open Git Bash.
    2. Run git reset --hard to revert any local changes. Note: this will delete all local changes! If you made local changes, make sure to backup those first, outside your FlightGear data directory! Or, better, learn to commit your changes to your local git repository.
    3. Run git pull and let it update, this can take a while.

Commiting changes

As a developer, you probably want to share your work with the world. For FlightGear, most developers do this by commiting stuff to the Git repository.

Getting started

  1. Register an account at Gitorious.
  2. Clone fgdata.
  3. Open Git Bash in your data directory and run ssh-keygen.
  4. Enter the name of the file in which you prefer to save the key and press Enter.
  5. Enter your password/passphrase and press Enter. You'll have to do this twice.
  6. Your key is now being generated. Open the .pub file with an editor (eg. Notepad++) and copy the content.
  7. Visit your dashboard at Gitorious and navigate to "Manage SSH keys".
  8. Click the "Add SSH key" button and paste the content of the .pub file. Follow the instructions on the screen.
  9. Open Git Bash in your data directory and run git remote add fgdata git://gitorious.org/fg/fgdata.git. This adds a remote ref to the master fgdata repository in Gitorious. You can also add the mapserver URL by running git remote add fgdata-mapserver git://mapserver.flightgear.org/fgdata/, which may be faster than Gitorious.
  10. Now run git remote set-url origin <url>, where <url> is the line that you get by clicking SSH on your fgdata clone page at Gitorious (should be something like git@gitorious.org:~your/fg/yours-fgdata.git). This switches the origin ref to the correct URL that Gitorious will take when updating.

It is recommended to split your new fgdata clone into separate local branches for your work. For instance, if you're working on the Boeing 747-400 and the aircraft reflection shader, you might create 2 branches named "747-400" and "reflect-shader". To do this,

  1. git checkout master
  2. git branch <branch name>
  3. git checkout <branch name>

Then you can make your changes to the new local branch(es), which will make merge requests easier for both yourself and committers. To switch in between branches, simply use

  • git checkout <branch name>

Pulling

To pull updates from the master fgdata repository,

  • <branch name> is the name of the branch you want to update.
  • <ref> is the repository ref. If you followed the getting started section, this will be "fgdata" or "fgdata-mapserver".
  1. git checkout <branch name>
  2. git pull <ref>
  3. Assuming you got no merging errors, run git push origin <branch name> to push the updates out to Gitorious.

Pushing

WIP.png Work in progress
This article or section will be worked on in the upcoming hours or days.
See history for the latest developments.

To push local updates to your fgdata clone,

  • <branch name> is the name of the local branch you want to push.
  1. git checkout <branch name>
  2. Use git status -- to list all the changed files.
    1. If you want to commit all changed files, run git commit -a and type your commit message.
    2. If you only want to commit some files, run git add <path/to/file> to add certain files (you can use git add --all <path/to/folder> to add all files within a certain folder) and git rm <path/to/file> to mark files you have removed for deletion in the repository.
  3. If you used git commit -a, the commit has already been created for you. Otherwise, run git commit -m "<commit message>" (quotes required), where <commit message> is the message for your commit (i.e. "747-400: Improved lightmaps").
  4. git push origin <branch name>

Rebase the development branch

Normally developments take some time, so the root of a development branch most likely will be outdated by the time the development is finished and a merge can be prepared. In order to make the merge easier for the contributor, it could be helpful to rebase the development branch to the current HEAD of the master.

Let <branch name> be the name of the local branch you want to push, that branch contains your work. Furthermore, fgdata refers to the repository at git://gitorious.org/fg/fgdata, i.e. the official repository, whereas origin refers to your personal Gitorious repository.(You can use git remote -v to learn about all the remotes and their names.)

  1. Switch to that branch: git checkout <branch name>
  2. Rebase your branch to the current HEAD of fgdata/master: git rebase fgdata/master
  3. Push your rebased development branch to your personal Gitorious repo
    1. First try git push origin. If that produces some warnings about merges, you can
    2. force it by using git push origin -f .

For more details on what rebasing does, check out http://book.git-scm.com/4_rebasing.html.

Creating a merge request

  1. Check that the commit to your fgdata clone is recognized by Gitorious.
  2. Click the "Request merge" button on your fgdata clone page. Loading the next page can take a while, as it will list all commits of the past years!
  3. Once again write a short summary (could be the same as used with git commit), but this time, also write an explanation of your merge request (what does it do). Make sure you set target repository to fgdata, Target Branch to master and Source Branch to the local branch with your updates.
  4. Tick the box in front of your commit and click the "Create merge request" button.
  5. Now, all you have to do is contact a contributor and wait untill he accepts your merge request ;)

Creating merge requests using this method literally means merging an entire branch into fgdata; this may not be desirable for some situations, such as small changes that only require one little commit. There's a neat method to only push certain commits to a merge request discussed by Anders Gidenstam on the FlightGear Forums.