FlightGear wiki - User contributions [en]

Scripted Compilation on Linux Debian/Ubuntu

2026-04-22T12:09:44Z

Rominet: OpenRTI support has been removed from download_and_compile.sh (after SG & FG in next)

<tt>download_and_compile.sh</tt> is a Bash script that takes care of downloading and compiling FlightGear and related software from their source code repositories with just one command execution for both 32-bit and 64-bit [https://www.debian.org/ Debian]-based systems. Pre-existing versions (if any) of the software installed by <tt>download_and_compile.sh</tt> are not touched at all since the script downloads, builds and installs everything under the directory in which it is launched. You can choose the particular components to download, build and install.

Unless told not to do so, <tt>download_and_compile.sh</tt> installs packages with <tt>apt-get</tt>. For this reason, it is primarily useful on Debian-based distributions. However, if one disables package installation (using <code>-pn</code> or <code>--sudo=echo</code>) and installs the corresponding dependencies oneself, it can be used on other Unix-like systems such as [https://fedoraproject.org/ Fedora Linux], [https://archlinux.org/ Arch Linux] or [https://www.openbsd.org/ OpenBSD].

== Introduction ==

<tt>download_and_compile.sh</tt> is a [https://www.gnu.org/software/bash/ Bash] script written for [https://www.debian.org/ Debian]-derived distributions ([https://www.ubuntu.com/ Ubuntu], [https://devuan.org/ Devuan], [https://www.linuxmint.com/ Linux Mint], etc.). Its purpose is to automatically install dependencies using the package manager, then build and install FlightGear-related programs.

By default, <tt>download_and_compile.sh</tt> installs most dependencies with <tt>apt-get</tt> run under <tt>sudo</tt>.<ref name="disabling-installation-of-dependencies-via-package-manager">If you think you already have the dependencies, this installation can be disabled either by using option <code>-pn</code> or by passing option <code>--sudo=echo</code> (the latter results in printing the <tt>apt-get</tt> command line without running it).</ref> Other dependencies, either because they aren't available in the standard APT repositories, or because of non-option arguments passed to <tt>download_and_compile.sh</tt>, are downloaded and compiled on the fly (this can be the case for [[PLIB]], [[Simgear]] and [[OpenSceneGraph]], for instance—it all depends on the arguments passed to the script).

<tt>download_and_compile.sh</tt> works in the directory it is run from: apart from dependencies installed via the package manager, all programs built by <tt>download_and_compile.sh</tt> are installed under the <tt>install</tt> subdirectory of the directory from which the script was run. In other words, installation of programs by <tt>download_and_compile.sh</tt> is clean, very easy to undo and doesn't interfere with other programs on the system.

It is possible to manage several directory trees with <tt>download_and_compile.sh</tt>; as far as it is concerned, such directory trees are completely independent from each other. For instance, if you run <tt>download_and_compile.sh</tt> in <tt>dir1</tt> and <tt>dir2</tt>, the programs installed under <tt>dir1</tt> won't “see” those installed under <tt>dir2</tt>, and vice versa.

Apart from its main purpose, <tt>download_and_compile.sh</tt> can be used to find hopefully up-to-date build-dependency information for FlightGear and related software. You would do so by inspecting {{fgmeta source
| path = download_and_compile.sh
| text = the script
}} at the point where it installs packages.<ref name="note-inspecting-download-and-compile-sh-to-gather-build-dependency-information">Look for strings such as <tt>zlib1g-dev</tt>, <tt>libglew-dev</tt> or <tt>qt5-default</tt>.</ref>

== Prerequisites ==

Before embarking on building your own FlightGear binaries, you need to install a few tools that <tt>download_and_compile.sh</tt> uses to retrieve and compile source code. These tools are found in the following packages on [https://www.debian.org/ Debian] systems (and presumably on most Debian derivatives too):

* build-essential
* git
* cmake

These packages can be installed by running a command such as:
$ sudo apt-get install build-essential git cmake
Once this is done, the <tt>download_and_compile.sh</tt> script can be run. Unless told otherwise, it will install additional tools and libraries as it runs, depending on the chosen components (this will be explained in further sections).

== Disk space requirements and build time ==

As of April 2019, building FlightGear requires about 12 [https://en.wikipedia.org/wiki/Gibibyte GiB] of disk space. Note that this includes downloaded source code for [[SimGear]] and FlightGear, generated build files and the large [[FGData]] repository (about 6 GiB for that one).

With an Intel Core i7 860 CPU (2.80 GHz) purchased in 2009, compiling [[SimGear]] and FlightGear 2019.2 with option <code>-j8</code> takes about 14 minutes. If you don't have a fast machine and build using only one core, it may require several hours.

== Download ==

You can get <tt>download_and_compile.sh</tt> {{fgmeta source
| path = download_and_compile.sh
| text = from FGMeta
}}. It is contained in the [[FGMeta]] repository, which is maintained by the FlightGear developers. The script can be downloaded from the link given above, however, for easier updates and in order to have the command <code>download_and_compile.sh --version</code> work as intended, it is recommended to get it as explained [[#getting-download-and-compile-sh-using-an-fgmeta-clone|below]].

In case you build stable versions of FlightGear using either of the <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> options of <tt>download_and_compile.sh</tt>, remember to update the script before trying to build a new version of FlightGear (see [[#updating-download-and-compile-sh-using-an-fgmeta-clone|Updating <tt>download_and_compile.sh</tt>]] below). Of course, you can update it more often in order to benefit from new features or bug fixes; this is especially useful if you are building ''next''—that is, the development branch of FlightGear.

== Getting started with <tt>download_and_compile.sh</tt> ==

=== For the impatient ===

So, you're in a hurry, want to build FlightGear but don't want to read any explanation? You can try what follows, but be aware that you may need to come back and read part of the the following sections if you encounter a problem. All commands should be run under a normal user account; however, unless you pass option <code>-pn</code> or something similar to disable installation of packages from your distribution, you'll be asked for your <tt>sudo</tt> password during execution of the <tt>download_and_compile.sh</tt> command (<tt>sudo</tt> is used by <tt>download_and_compile.sh</tt> to run commands like <tt>apt-get</tt>). So, here is your quick recipe for getting <tt>download_and_compile.sh</tt> and using it to build FlightGear:
mkdir -p ~/flightgear/dnc-managed
cd ~/flightgear
{{fgmeta clone | protocol = https}}
cd ~/flightgear/dnc-managed
~/flightgear/fgmeta/download_and_compile.sh -s -j$(nproc)
./run_fgfs.sh --launcher

The <code>-s</code> option passed to <tt>download_and_compile.sh</tt> instructs it to build the latest stable release of FlightGear. Use option <code>--lts</code> instead if you want the latest Long Term Stable release (it may be older but possibly more stable), or <code>--old-lts</code> for the previous LTS release. If you pass none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, <tt>download_and_compile.sh</tt> will build the ''next'' suite, which contains the development version of FlightGear. For more details on these options, see [[#Release selection|Release selection]].

The command <tt>run_fgfs.sh --launcher</tt> starts the [[FlightGear Qt launcher|FlightGear built-in launcher]]. This is often convenient but not compulsory. Another way to start FlightGear could be <code>./run_fgfs.sh --airport=PHTO --aircraft=c172p</code>. There are plenty of other options, which are listed by <code>./run_fgfs.sh --help --verbose</code>.

In some cases, <tt>download_and_compile.sh</tt> stops and waits for your answer before continuing. This is done when there is something important that you should know. When you are used to these prompts and would rather not see them anymore, pass the <code>--non-interactive</code> option to suppress them.

More detailed instructions are given below. The following sections also explain how to update <tt>download_and_compile.sh</tt> and FlightGear.

=== Notations ===

When a command should be run as an unpriviledged user, it will be preceded by a dollar sign:
$ whoami
toto
In contrast, a hash sign (#) means that the command must be run with superuser privileges to achieve the desired effect:
# whoami
root

In order to make instructions easy to understand, two directories (= folders) will be consistently used for the same purpose below:
* <tt>~/flightgear/fgmeta</tt> will contain a clone of the [[FGMeta]] repository; therefore, <tt>download_and_compile.sh</tt> will reside in that directory;
* <tt>~/flightgear/dnc-managed</tt> will be the directory from which we run <tt>download_and_compile.sh</tt>. In other words, with this setup, a typical sequence of commands could be:
$ cd ~/flightgear/dnc-managed
$ ~/flightgear/fgmeta/download_and_compile.sh
or
$ cd ~/flightgear/dnc-managed
$ ~/flightgear/fgmeta/download_and_compile.sh CARES PLIB SIMGEAR FGFS DATA OSG
These are of course just examples. The aforementioned paths are not hardwired anywhere in the script; you are free to choose the directories you want for these purposes.

=== Getting <tt>download_and_compile.sh</tt> the “right way” ===

There are several ways to obtain {{fgmeta source
| path = download_and_compile.sh
| text = download_and_compile.sh
}}. The method described here makes it very easy to update the script and causes the command <code>download_and_compile.sh --version</code> to work as intended.

As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we want to clone the [[FGMeta]] repository in <tt>~/flightgear/fgmeta</tt> and work with its ''next'' branch. Let's go:
$ mkdir -p ~/flightgear
$ cd ~/flightgear
$ {{fgmeta clone | protocol = https}}
You now have a fresh FGMeta clone in <tt>~/flightgear/fgmeta</tt> and your brand new <tt>download_and_compile.sh</tt> script is located in that directory. You can already try it to see the available options:
<pre>$ ~/flightgear/fgmeta/download_and_compile.sh --help
download_and_compile.sh [OPTION...] [--] [COMPONENT...]
Download and compile components belonging to the FlightGear ecosystem.

Without any COMPONENT listed, or if ALL is specified, recompile all
components listed in the WHATTOBUILDALL variable. Each COMPONENT may
be one of the following words:

ALL, ATCPIE, CARES, CMAKE, DATA, FFGO, FGFS, FGRUN, FGX, OPENRADAR, OSG, PLIB, SIMGEAR, TERRAGEAR, TERRAGEARGUI, ZLIB.

Available options:
-h, --help show this help message and exit
--version print version and license information, then exit

(...)</pre>

=== Updating <tt>download_and_compile.sh</tt> ===

Now that you have <tt>download_and_compile.sh</tt> from the [[FGMeta]] repository, it is very easy to update (this assumes you didn't modify anything yourself inside <tt>~/flightgear/fgmeta</tt>!):
$ cd ~/flightgear/fgmeta && git pull

If you want to keep updates as easy as we just showed, it is best not to modify <tt>download_and_compile.sh</tt> yourself. <tt>download_and_compile.sh</tt> has plenty of options that usually make it unnecessary to modify the script. Just run <code>download_and_compile.sh --help</code> and learn about the available options when you feel the need to change something. Unless you have special needs that can only be accomodated by modifying <tt>download_and_compile.sh</tt>, you are invited to skip to the next section.

If you really, ''really'' want to modify <tt>download_and_compile.sh</tt> while keeping updates easy, a good technique is to add your changes to your FGMeta clone in the form of one or more Git ''commits'' (no need to push them anywhere, commits can remain in your clone). How to do that is beyond the scope of this document, though; read Git tutorials if you want to learn it (there are plenty on the Internet). Once you have committed your changes to your FGMeta clone, make sure the repository is clean (use <code>git status</code>), then update it with:
$ cd ~/flightgear/fgmeta && git pull --rebase
This will apply your commits on top of the latest commit of the branch that is currently checked out, which so far contained the official version of <tt>download_and_compile.sh</tt>. In case your changes conflict with the update, Git will tell you and you'll have to resolve the conflict manually (look for “Git resolve conflict” on your favorite search engine)... or start again from a pristine [[FGMeta]] clone.

=== Building FlightGear ===

In what follows, we won't give the full path to <tt>download_and_compile.sh</tt> when showing commands to be run, but you should prepend it to <tt>download_and_compile.sh</tt> whenever you see a <tt>download_and_compile.sh</tt> command. For instance, if you used the same path as in [[#getting-started-with-download-and-compile-sh-notations|Notations]] and see the command:
$ download_and_compile.sh --help
what you should actually run is:
$ ~/flightgear/fgmeta/download_and_compile.sh --help

Apart from this harmless command, ''do not'' run other <tt>download_and_compile.sh</tt> commands from an arbitrary directory, in particular ''don't'' run them from <tt>~/flightgear/fgmeta</tt>. This is because '''most other <tt>download_and_compile.sh</tt> commands write to the current directory''' (<code>download_and_compile.sh --help</code> and <code>download_and_compile.sh --version</code> are safe to run from any directory, though).

Of course, it is always possible to make commands shorter by setting up aliases (see tips at the end of [https://sourceforge.net/p/flightgear/mailman/message/36634426/ this message]), by adding the directory containing <tt>download_and_compile.sh</tt> to your <tt>PATH</tt> or by creating a symbolink link pointing to <tt>download_and_compile.sh</tt> in a directory that is part of your <tt>PATH</tt>. This is not necessary, though; do it only if you feel the need (when enabled, persistent shell history is often enough to obviate the need to extend the <tt>PATH</tt>).

{{Note|The following commands should be run from an empty directory<ref name="dedicated-directory-won-t-stay-empty-forever">Well, empty before the first time; later, <tt>download_and_compile.sh</tt> is going to populate it with plenty of FlightGear files and subdirectories, of course.</ref> in a partition that has enough free space (see [[#disk-space-requirements-and-build-time | Disk space requirements and build time]]). As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we are going to choose the directory <tt>~/flightgear/dnc-managed</tt> for this purpose, in order to express that the whole directory tree is managed by <tt>download_and_compile.sh</tt>. This is just an example; feel free to choose another directory if you want.

'''Don't run the commands from a non-dedicated directory,''' because it will be filled with files and directories created by <tt>download_and_compile.sh</tt> and the FlightGear, SimGear, etc. build systems. That would be a complete mess! In particular, ''don't'' run the commands from the directory containing your [[FGMeta]] clone.}}

{{Tip|For some commands, <tt>download_and_compile.sh</tt> may use <tt>sudo</tt>. In case you want to run some other program instead of <tt>sudo</tt>, this can be done with the <code>--sudo</code> option of <tt>download_and_compile.sh</tt>. For instance, in order to see the commands that would be run with sudo without actually running them, you can pass <code><nowiki>--sudo=echo</nowiki></code> to <tt>download_and_compile.sh</tt>. Like all other options, <code>--sudo</code> must be given ''before'' all arguments that are component names (such as <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt>, etc.).}}

The package manager used by <tt>download_and_compile.sh</tt> by default is <tt>apt-get</tt> (it won't be used if you pass <tt>download_and_compile.sh</tt> the <code>-pn</code> option). You can use another one if you wish, as long as it supports the following calls:
''pkg-mgr'' update
''pkg-mgr'' install ''pkg1 pkg2'' ...
This is the case for <tt>aptitude</tt> as well as <tt>apt</tt>. If you want <tt>download_and_compile.sh</tt> to use <tt>aptitude</tt>, give it the option <code><nowiki>--package-manager=aptitude</nowiki></code> before any of the ''COMPONENT'' arguments.

All options of <tt>download_and_compile.sh</tt> can be seen by running the following command:
$ download_and_compile.sh --help

Now the instructions. '''You have chosen a dedicated directory''' where all the stuff that is downloaded and built by <tt>download_and_compile.sh</tt> will be stored. This is <tt>~/flightgear/dnc-managed</tt> if you followed the suggestions given in [[#getting-started-with-download-and-compile-sh-notations|Notations]], and should be empty before you run <tt>download_and_compile.sh</tt> for the first time. However, it is quite correct to start <tt>download_and_compile.sh</tt> from the same directory for subsequent runs, even when non-empty (otherwise, <tt>download_and_compile.sh</tt> would automatically reclone the repositories every time you run it; that would be a sheer waste of time and bandwidth). All that remains to do is to run:
$ mkdir -p ~/flightgear/dnc-managed
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh -s -j$(nproc)
The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

{{Note|Because of the <code>-s</code> option, the above <tt>download_and_compile.sh</tt> command would build the latest stable release of FlightGear. If you want to build the latest Long Term Stable release, use <code>--lts</code> instead. For the previous LTS release, use <code>--old-lts</code>. If you want to build the development version of FlightGear, use none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, but be warned: it may very well be unstable and unsuitable for flying. For more details on these options, see [[#Release selection|Release selection]].}}

When you don't pass any non-option argument to <tt>download_and_compile.sh</tt> as done here, it takes care of the base components needed to run FlightGear in good conditions: <tt>CARES</tt>, <tt>PLIB</tt>, <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> (these are the component names used by <tt>download_and_compile.sh</tt>, i.e., the final arguments one can optionally give in a <tt>download_and_compile.sh</tt> command; in normal speech, they correspond to the {{github source
| proj = c-ares
| repo = c-ares
| text = c-ares
}}, {{sourceforge source
| proj = libplib
| repo = code
| text = PLIB
}}, {{simgear source
| text = SimGear
}}, {{flightgear source
| text = FlightGear
}} and {{fgdata source
| text = FGData
}} repositories, as well as a suitable repository for [[OpenSceneGraph]]). Therefore, the above command is presently exactly equivalent to:
$ download_and_compile.sh -s -j$(nproc) CARES PLIB SIMGEAR FGFS DATA OSG

In case you want to build another component such as, say, CMAKE, you can add it to the command, like this:
$ download_and_compile.sh -s -j$(nproc) CARES PLIB SIMGEAR FGFS DATA OSG CMAKE

When the command terminates, you should have a script called <tt>run_fgfs.sh</tt> in the directory from which you ran <tt>download_and_compile.sh</tt> (i.e., <tt>~/flightgear/dnc-managed</tt> in the suggested setup). This will be your script to run FlightGear. For instance, in order to start the [[FlightGear Qt launcher|built-in launcher]], you can run the following commands:<ref name="no-need-to-change-to-dnc-managed-dir-before-starting-generated-scripts">We give these commands because they are easy to read, but the <code>cd</code> command is not needed if you use the correct path, as in <code>~/flightgear/dnc-managed/run_fgfs.sh --launcher</code>.</ref>
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --launcher
(You may omit the <code>--launcher</code> option; this would simply start FlightGear without any launcher, at the default airport and with the default aircraft.) 
In case you find this tedious to type or have more arguments to pass on a regular basis, you can follow the advice given at the end of [https://sourceforge.net/p/flightgear/mailman/message/36634426/ this message] or use another launcher such as [[FFGo]]—but the [[FlightGear Qt launcher|FlightGear built-in launcher]] started with <code>run_fgfs.sh --launcher</code> is quite fine, be sure to try it first!

{{Note|If you ran <tt>download_and_compile.sh</tt> from <tt>~/flightgear/dnc-managed</tt> as proposed above, the full path of the <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> directory is your [[$FG_ROOT]]. This is a very important path for FlightGear; knowing this may be useful for troubleshooting or doing “advanced things.”}}

=== Updating FlightGear ===

{{Note|If you built FlightGear with either of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, you need to pass the ''same option'' to the <tt>download_and_compile.sh</tt> command given below that will update your FlightGear installation. Otherwise, <tt>download_and_compile.sh</tt> will automatically build the ''next'' suite (bleeding-edge development version), which is probably not what you wish. Moreover, if you do want to switch from one suite to another (for instance from ''stable'' to ''next'', or from ''Long Term Stable'' to ''stable''), using the <code>--cleanup</code> option of <tt>download_and_compile.sh</tt> is heartily recommended.}}

Keeping the above note in mind, go to the directory from which you previously ran <tt>download_and_compile.sh</tt> (<tt>~/flightgear/dnc-managed</tt> in the [[#Notations|suggested setup]]). This is the folder which, if you did a complete run of <tt>download_and_compile.sh</tt> as shown in the previous section, contains the <tt>run_fgfs.sh</tt> script and a log file named <tt>compilation_log.txt</tt> that records what <tt>download_and_compile.sh</tt> did in its last run. If you wish to update, say, {{simgear source
| text = SimGear
}}, {{flightgear source
| text = FlightGear
}}, {{fgdata source
| text = FGData
}} and [[OpenSceneGraph|OSG]], simply execute this:
$ download_and_compile.sh -I -pn -j$(nproc) SIMGEAR FGFS DATA OSG
The <code>-I</code> option tells <tt>download_and_compile.sh</tt> to ignore inter-component dependencies. If you don't use it, other components may be processed too due to these dependencies. The purpose of the behaviour without <code>-I</code> is to help people who aren't necessarily aware of new requirements as time goes (e.g., SIMGEAR and FGFS started to require CARES by the end of 2024; a FlightGear fork of OSG is also required for FGFS ''next'' in 2025). However, it may be frustrating to specify a list of components and see additional ones being automatically added, hence the option.

The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

<tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> are called ''components'' in <tt>download_and_compile.sh</tt> terminology. A component generally corresponds to a software repository, or something close.

Now about the <code>-pn</code>. It is equivalent to <code>-p n</code> and means “don't try to install or update packages from my (Linux) distribution” (<code>y</code> means ''yes, please install or update'', <code>n</code> means ''no, please don't''). In case you forgot that, simply run:
$ download_and_compile.sh --help
What does it imply to pass <code>-pn</code>? This tells <tt>download_and_compile.sh</tt> to completely skip the step where it checks for needed packages from your distribution and installs/updates them, by default using <tt>apt-get</tt>. It thus goes straight to the following steps:
* update each repository corresponding to one of the selected components (<tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> in our example);
* compile each selected component that requires compilation;
* install each selected component in the appropriate place (under <tt>~/flightgear/dnc-managed</tt> according to our [[#getting-started-with-download-and-compile-sh-notations|Notations]]).
In case you don't have all required dependencies for the selected components, one of them is likely to fail, of course, since by passing <code>-pn</code> to <tt>download_and_compile.sh</tt>, you forbid it to install these dependencies for you. So, you can also very well update without passing the <code>-pn</code> option, it will simply take a little longer (the time to check if all dependencies of the selected components are available with <tt>APT</tt>). In fact, this is '''what you should do if the previous <tt>download_and_compile.sh</tt> run failed:''' first update <tt>download_and_compile.sh</tt> (see [[#getting-download-and-compile-sh-using-an-fgmeta-clone|above]]) then run it ''without'' <code>-pn</code><ref name="passing-no-pn-option-equals-passing-py">Which is the same as passing <code>-py</code>.</ref> in case new dependencies have been recently added and you don't have them on your system yet—this would be a very likely cause for the failure. In this case, running <code>download_and_compile.sh --cleanup</code> to restart the build from a clean state is probably a good idea (see [[#Cleaning built and installed files|Cleaning built and installed files]] for details on this option).

'''Summary'''

Routine update:
$ download_and_compile.sh -pn -j$(nproc) ''COMPONENT...''
(add <code>-I</code> if you don't want inter-component dependencies to pull additional components). In case this fails, first update <tt>download_and_compile.sh</tt> (see [[#getting-download-and-compile-sh-using-an-fgmeta-clone|above]]), then run
$ download_and_compile.sh --cleanup
$ download_and_compile.sh -j$(nproc) ''COMPONENT...''
where ''COMPONENT...'' stands for the space-separated list of components you want <tt>download_and_compile.sh</tt> to process.

=== Examining the history of <tt>download_and_compile.sh</tt> ===

Looking at the latest commits that affected <tt>download_and_compile.sh</tt> is quite easy with your FGMeta clone:
$ cd ~/flightgear/fgmeta
$ git log -- download_and_compile.sh
(then quit by typing <tt>q</tt>, assuming your <tt>$GIT_PAGER</tt> is <tt>less</tt>) 

In order to do the same, but also see the patch for each commit:
$ cd ~/flightgear/fgmeta
$ git log -p -- download_and_compile.sh

=== For the curious: the SSH way ===

{{Note|The method described below is not necessary anymore since {{fgmeta commit | 420034d5b51ff2d32fc0c3716b17a2d862841e0f}} (May 2020). Also, it was written at a time where the canonical location for [[FGData]] was at SourceForge; however, in 2025, the canonical location for FGData is {{fgdata source
| text = here
}}.}}

The purpose of this section is to teach you how to clone [[FGData]] using SSH, then change the Git remote setup in your clone of that repository to retrieve further updates using https—which is convenient, as it does not require you to provide a password. This technique used to be necessary to securely retrieve FGData because of a problem in the [https://sourceforge.net/ SourceForge] infrastructure (namely, <code>git clone</code> from SourceForge doesn't work for the big FGData repository using https). This is not needed anymore in 2025.

Because the following method will make you connect to [https://sourceforge.net/ SourceForge] using the SSH protocol, you'll need an account on that site. If you don't already have one, go to the [https://sourceforge.net/user/registration registration page] and create an account. In all this section, we'll assume that your account name at SourceForge is ''SFusername''.

{{Note|As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we assume that your Unix user name (login) is <tt>toto</tt>. Don't confuse the <tt>sudo</tt> password prompt (where you need to enter <tt>toto</tt>'s password) with the password prompt for your SourceForge account! The former appears as
[sudo] password for toto:
whereas the latter is just:
Password:
}}

{{Tip|For some commands, <tt>download_and_compile.sh</tt> may use <tt>sudo</tt>. In case you want to run some other program instead of <tt>sudo</tt>, this can be done with the <code>--sudo</code> option of <tt>download_and_compile.sh</tt>. For instance, in order to see the commands that would be run with sudo without actually running them, you can pass <code><nowiki>--sudo=echo</nowiki></code> to <tt>download_and_compile.sh</tt>. Like all other options, <code>--sudo</code> must be given ''before'' all arguments that are component names (such as <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt>, etc.).}}

{{Note|The commands given below will build the ''next'' suite, which contains the bleeding-edge development version of FlightGear. This is likely to be unstable, possibly unsuitable for flying. If you'd rather build the latest stable release or the latest Long Term Stable release, add option <code>-s</code> or <code>--lts</code> to all <tt>download_and_compile.sh</tt> commands given below (or <code>--old-lts</code> for the previous LTS release). You may add the chosen option right after the <tt>download_and_compile.sh</tt> command name (in any case, the option should come before non-option arguments such as SIMGEAR, FGFS, DATA, etc.). See [[#Release selection|Release selection]] for more explanations on options <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>.}}

Now the instructions. You have chosen a dedicated directory where all the stuff that is downloaded and built by <tt>download_and_compile.sh</tt> will be stored. This is <tt>~/flightgear/dnc-managed</tt> in our example, and should be empty before you run <tt>download_and_compile.sh</tt> for the first time. However, it is quite correct to start <tt>download_and_compile.sh</tt> from the same directory for subsequent runs, even when non-empty (otherwise, <tt>download_and_compile.sh</tt> would automatically reclone the repositories every time you run it; that would be a sheer waste of time and bandwidth).

Ready? Let's go!
<pre>$ mkdir -p ~/flightgear/dnc-managed
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
Fetching DATA with 'git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata'
Cloning into '.'...
The authenticity of host 'git.code.sf.net (216.105.38.16)' can't be established.
ECDSA key fingerprint is SHA256:FeVkoYYBjuQzb5QVAgm3BkmeN5TTgL2qfmqz9tCPRL4.
Are you sure you want to continue connecting (yes/no)?
Warning: Permanently added 'git.code.sf.net,216.105.38.16' (ECDSA) to the list of known hosts.
Connection closed by 216.105.38.16 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
</pre>

The above messages are perfectly normal but deserve a little explanation. Here, <tt>ssh</tt> asked us to confirm that the fingerprint sent by the remote host is that of the real <tt>git.code.sf.net</tt>, as opposed to that of some malicious server ''pretending'' to be <tt>git.code.sf.net</tt>. This confirmation only has to be done once, after which it is remembered thanks to <tt>~/.ssh/known_hosts</tt>. You should visit the [https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/#fingerprint-listing page that gives the host key fingerprint of every publically-accessible SSH server at SourceForge] and carefully check that the fingerprint appearing on your terminal is listed on that page for <tt>git.code.sf.net</tt>, or some matching pattern such as <tt>*.code.sf.net</tt>.

If the fingerprint that is printed on your terminal is not listed on that page, answer <tt>no</tt> to the question ''Are you sure you want to continue connecting (yes/no)?'' and copy/paste to flightgear-devel (see [[Mailing lists]]) the above message from <tt>ssh</tt> that contains the fingerprint sent to you by the remote host which pretends to be <tt>git.code.sf.net</tt>. If this happened, you should stop here and wait for answers from readers of flightgear-devel.

From now on, we'll assume that the fingerprint you received was correct, and therefore that you have answered <tt>yes</tt> to the ''Are you sure you want to continue connecting (yes/no)?'' question.

In this example, it took us several minutes to verify the fingerprint of the <tt>git.code.sf.net</tt> server and confirm it to <tt>ssh</tt>. Because of this delay, <tt>git.code.sf.net</tt> hung up on us and closed the connection. This is absolutely ''not a problem:'' we can just rerun the <tt>download_and_compile.sh</tt> command with the same arguments as the first time. Since we answered <tt>yes</tt> to the ''Are you sure you want to continue connecting (yes/no)?'' prompt, the fingerprint of <tt>git.code.sf.net</tt>'s key has been stored in <tt>~/.ssh/known_hosts</tt>, therefore we won't get this prompt anymore. But if some server claiming to be <tt>git.code.sf.net</tt> presents a host key that has a different fingerprint in the future, <tt>ssh</tt> will print a big fat warning that the server may belong to an attacker trying to impersonate <tt>git.code.sf.net</tt>. Therefore, this SSH host key verification is very useful to protect us from future attacks (which hopefully won't happen at all).

As said, we just rerun the <tt>download_and_compile.sh</tt> command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
Fetching DATA with 'git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata'
Cloning into '.'...
Password:</pre>
As explained above, the preceding prompt is for your SourceForge password (which you could guess from the <code><nowiki>git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata</nowiki></code> command).
<pre>remote: Enumerating objects: 67011, done.
remote: Counting objects: 100% (67011/67011), done.
remote: Compressing objects: 100% (31342/31342), done.
remote: Total 67011 (delta 38776), reused 59640 (delta 33570)
Receiving objects: 100% (67011/67011), 2.60 GiB | 313.00 KiB/s, done.
Resolving deltas: 100% (38776/38776), done.
Checking out files: 100% (12959/12959), done.
Password:</pre>
(It will take a fair amount of time to get there, because this is the complete download of [[FGData]].) 
This is again a prompt for your SourceForge password, because <tt>download_and_compile.sh</tt> wants to run <code>git pull --rebase</code> in the repository (admittedly, it's a bit dumb after a <tt>clone</tt> operation—please forgive us). In case you were not monitoring the <tt>clone</tt> operation, you probably saw the password prompt way after <tt>git.code.sf.net</tt> got bored waiting for you and closed our second connection:
<pre>Connection closed by 216.105.38.16 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.</pre>
(if not, there should be no error message and you should have a clean FGData clone) 
No worries. Just as before, simply rerun the command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
DATA: the repository already exists
Password:
Already up to date.
Current branch next is up to date.
Already on 'next'
Your branch is up to date with 'origin/next'.
All optional package alternatives have found a matching package.

download_and_compile.sh has finished to work.
</pre>
There we are! You now have a clean, up-to-date [[FGData]] clone in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> (remember: <tt>~/flightgear/dnc-managed</tt> is the directory from which you ran <tt>download_and_compile.sh</tt>). Note this place: the full path of the <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> directory is your [[$FG_ROOT]].

Now, change the protocol to use for future updates of your FGData clone:<ref name="changing-the-protocol-for-a-git-remote-manual-method">Another way would be to manually change the relevant line starting with <code>url = <nowiki>ssh://SFusername@</nowiki></code> for the <code>origin</code> remote in the <tt>.git/config</tt> file that lives inside your repository clone (i.e., <tt>~/flightgear/dnc-managed/install/flightgear/fgdata/.git/config</tt> in our example).</ref>
(cd install/flightgear/fgdata && \
git remote set-url origin <nowiki>https://git.code.sf.net/p/flightgear/fgdata</nowiki>)
(you can check at any time the protocol(s) in use with the command <code>git remote -v</code> run inside a Git repository—in this case, inside the folder <tt>install/flightgear/fgdata</tt>). As a consequence of this change, all future updates of your FGData clone will use the <tt>https</tt> protocol, therefore you won't be prompted anymore for your SourceForge password.

All that remains to do is to run, from the same directory as before (<tt>~/flightgear/dnc-managed</tt> in our example):
$ download_and_compile.sh -j$(nproc)
The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

Assuming the compilation was successful, you can now start the [[FlightGear Qt launcher|FlightGear built-in launcher]] using for instance:
$ ./run_fgfs.sh --launcher
See [[#Building FlightGear|Building FlightGear]] for more details.

== List of available components ==

The <tt>download_and_compile.sh</tt> script is able to download, compile (when applicable) and install the following components:

* ATCPIE (for the [[ATC-pie]] air traffic control simulation program)
* CMAKE (for the [https://cmake.org/ CMake] build tool—this can be useful in case CMake is too old in your distribution)
* DATA (for [[FGData]], the main set of data files used by FlightGear)
* FGFS (for FlightGear itself)
* FFGO (for the [[FFGo]] FlightGear launcher)
* FGRUN (for the [[Fgrun|FGRun]] FlightGear launcher)
* FGX (for the [[FGX|FGx]] FlightGear launcher<ref name="note-on-the-status-of-FGx-support-in-download-and-compile-sh">Support for FGx in <tt>download_and_compile.sh</tt> would probably benefit from a code review.</ref>)
* OPENRADAR (for the [[OpenRadar]] air traffic control simulation program)
* OSG (for the [[OpenSceneGraph]] library)
* PLIB (for the [[PLIB]] library)
* SIMGEAR (for the [[SimGear]] library—foundation for FlightGear and TerraGear)
* TERRAGEAR (for the [[TerraGear]] terrain building toolchain)
* TERRAGEARGUI (for [[TerraGear GUI]], a graphical interface for TerraGear)
* ZLIB (for the [http://www.zlib.net/ zlib] compression library)

Each of the items listed above is a ''component'' in <tt>download_and_compile.sh</tt> terminology. Components are written in uppercase by convention.

{{Note|The preceding list might not be up-to-date. The up-to-date list of components supported by <tt>download_and_compile.sh</tt> can always be obtained by running <code>download_and_compile.sh --help</code>.}}

What is the point of knowing this? Because you may pass component names to <tt>download_and_compile.sh</tt> in order to tell it what you want to download, build and install. By default, only the components [[SimGear|SIMGEAR]], [[FlightGear|FGFS]], [[FGData|DATA]] and [[OpenSceneGraph|OSG]] are taken care of, which means that the command:
$ download_and_compile.sh
is equivalent to:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

In case you'd like to do the same build with just [[PLIB]] added, you could use:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG PLIB

You get the idea. When several components are passed on the same command line, <tt>download_and_compile.sh</tt> chooses a reasonable order for processing, so don't worry about that.

== When building ''next'', you may encounter problems ==

Keeping in mind that this script compiles sometimes bleeding edge software, it can happen that what was successfully compiling last week, does not compile anymore today. Building the latest stable version (option <code>-s</code>) or the latest Long Term Stable release (option <code>--lts</code>) should always work, unless there is a problem with the script (well, in some cases, there may be packages of your distribution that are too recent for <code>--lts</code>; for instance, in July 2020, <code>--lts</code> didn't build with OpenSceneGraph 3.6, but simply passing the OSG component on the <tt>download_and_compile.sh</tt> command solved the problem, because at that time, option <code>--lts</code> selected OpenSceneGraph 3.4).

That said, you may want to build the development version (called ''next''): this is the one developers use all the time, so kindly asking on the flightgear-devel [[Mailing_lists|mailing list]] in case a problem popped up<ref name="what-to-provide-when-asking-for-help">Don't forget in this case to precisely tell what you did and include the <tt>compilation_log.txt</tt> file written by <tt>download_and_compile.sh</tt>.</ref> should allow you to find good advice and get the problem quickly fixed, if it's a new one.

{{Warning|As of July 2020, heavy development will be done on ''next'', the development branch of FlightGear. It is expected to be rather unstable for several months. Unless you are really interested in FlightGear development or in providing feedback to the developers, you're probably better off building either the latest stable version (option <code>-s</code>) or the latest Long Term Stable release (option <code>--lts</code>). In case you want something even older, the previous LTS release can be selected with option <code>--old-lts</code>.}}

== Task-specific instructions ==

{{Note|In this section, we assume you've read and followed the advice given in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]].}}

=== Selecting the components to build ===

By default, <tt>download_and_compile.sh</tt> downloads or updates, then compiles, [[SimGear]], FlightGear, [[FGData]] and [[OpenSceneGraph|OSG]] (more precisely, FGData is downloaded but not compiled—that wouldn't make sense). This is what happens when running:
$ download_and_compile.sh
The preceding command is therefore equivalent to:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

To make <tt>download_and_compile.sh</tt> take care of other programs or libraries, use non-option arguments naming the ''components'' you want, for instance:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG CMAKE
SIMGEAR, FGFS, DATA, OSG and CMAKE are the component names respectively corresponding to [[SimGear]], FlightGear, [[FGData]], [[OpenSceneGraph]] and [https://cmake.org/ CMake] in <tt>download_and_compile.sh</tt>'s terminology.

A [[#list-of-available-components|list of available components]] is provided on this page, but the fully up-to-date list can always be obtained by running <code>download_and_compile.sh --help</code>.

=== Choosing between stable and development versions ===

By default, <tt>download_and_compile.sh</tt> fetches code and data from development branches of the source repositories (which sometimes causes compilation or runtime errors). However, it is possible to tell the script to download the latest “stable” version of each component, for some suitable definition of “stable”. This is by means of the <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> options:
$ download_and_compile.sh -s ''COMPONENT1 COMPONENT2...''
or
$ download_and_compile.sh --lts ''COMPONENT1 COMPONENT2...''
or
$ download_and_compile.sh --old-lts ''COMPONENT1 COMPONENT2...''

How does it work?
* For [[SimGear]], FlightGear and [[FGData]], <code>-s</code> uses the most recent stable release branch of the corresponding Git repository, <code>--lts</code> uses the most recent Long Term Stable release (LTS) and <code>--old-lts</code> uses the previous LTS release.
* For other components, a known-stable version is selected by <tt>download_and_compile.sh</tt>, which may be influenced by the use of <code>-s</code>, <code>--lts</code> or <code>--old-lts</code>.

So, as far as the SIMGEAR, FGFS and DATA components are concerned, you can:
* build the latest stable release (<code>-s</code>);
* build the latest Long Term Stable release (<code>--lts</code>);
* build the previous Long Term Stable release (<code>--old-lts</code>);
* build the current development version (bleeding edge), which lives in the {{flightgear source
| branch = next
| text = next
}} branch of the FlightGear repository.
The use of <code>-s</code>, <code>--lts</code> or <code>--old-lts</code> also influences the version of other components you may have selected (this can be overridden using <code>--component-branch</code> for advanced users—see [[#Component-specific settings|Component-specific settings]]).

{{Note|In a given folder where <tt>download_and_compile.sh</tt> is run, you should normally either always use the <code>-s</code> option, or always use <code>--lts</code>, or always use <code>--old-lts</code>, or always none of these (in other words, stick to the same suite: latest stable, latest LTS, previous LTS or ''next'', consistently accross all components).}}

Actually, it ''is'' possible to switch between suites but you have to use the <code>--cleanup</code> option when doing the switch (see [[#Cleaning built and installed files|Cleaning built and installed files]] for information on this option). For instance:
* Build with <code>-s</code> as many times as you want.
* Want to try ''next''? Okay, then build once with <code>--cleanup</code> (no <code>-s</code> option anymore).
* You can then perform as many builds of ''next'' as you want; no need to use <code>--cleanup</code> unless something special went wrong.
* If you later decide to switch back to the stable release, build once with <code>-s</code> and <code>--cleanup</code>, then only with <code>-s</code> for further builds.
* etc.

This way, ''you don't need to download the repositories again'' when trying the various suites. In particular, you can switch between ''next'', stable, LTS and old LTS without downloading nor having several copies of [[FGData]] on your hard drive. (This works because a Git repository may internally contain data for several branches, even if only one is “normally visible” in the filesystem at a given time.)

==== Building the latest Long Term Stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>--lts</code> option to build the latest Long Term Stable release:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --lts
(In this example, the implicitly-selected components are SIMGEAR, FGFS and DATA, as explained [[#selecting-the-components-to-work-on | above]].)

{{Note|If you decide to use the <code>--lts</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>--lts</code> option for some components and not for others is not supported.}}

==== Building the latest stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>-s</code> option to build the latest stable release:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh -s

{{Note|If you decide to use the <code>-s</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>-s</code> option for some components and not for others is not supported.}}

==== Building the current FlightGear development version ====

When executing <tt>download_and_compile.sh</tt> without any option, the development version of every selected component is built:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh

{{Note|The development version of FlightGear changes on an almost daily basis. It provides the latest features, but is not guaranteed to always work reliably. If you don't want to take the risk of finding new bugs when updating, you may prefer to use the latest stable release.}}

==== Building the previous Long Term Stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>--old-lts</code> option to build the previous Long Term Stable release (i.e., oldish code):
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --old-lts
(In this example, the implicitly-selected components are SIMGEAR, FGFS and DATA, as explained [[#selecting-the-components-to-work-on | above]].)

{{Note|If you decide to use the <code>--old-lts</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>--old-lts</code> option for some components and not for others is not supported.}}

=== Overriding the source repository or branch for a component ===

This section shows how to override the location and/or branch from which a given component will be downloaded.

{{Warning|The rest of this section is for people who know what they are doing. Don't use the following unless you trust the person who publishes the repository and have good reasons to believe that it has been kept up-to-date.}}

==== A short example ====

Let's start with an example to make it easier to understand to following paragraphs. Suppose we want to build the current stable release of FlightGear, linked against an [[OpenSceneGraph]] library whose source code is to be retrieved from branch <tt>fgfs-osg-36-2</tt> of the Git repository located at [https://gitlab.com/flightgear/openscenegraph.git https://gitlab.com/flightgear/openscenegraph.git] (this is actually the default in September 2024). Since the default protocol used when <tt>download_and_compile.sh</tt> clones a repository is [https://en.wikipedia.org/wiki/HTTPS HTTPS], this can be done with
download_and_compile.sh --cleanup -s \
--override-repo OSG=GitLab:gitlab.com/flightgear/openscenegraph.git \
--component-branch OSG=fgfs-osg-36-2 SIMGEAR FGFS DATA OSG

==== The site name ====

<tt>download_and_compile.sh</tt> uses case-insensitive short names such as <tt>GitLab</tt>, <tt>GitHub</tt>, <tt>SourceForge</tt> and <tt>gitlab.kitware.com</tt> as keys in order to identify the settings describing where and how a given component will be initially fetched (these settings are effective at clone time; later updates simply use the settings recorded in the local repository). These names are referred to as ''site'' in the output of <code>download_and_compile.sh --help</code>, in particular in the <tt>--git-clone-site-params</tt> and <tt>--override-repo</tt> options we'll present below. These ''site'' keys are simply identifier strings; they are not used in the DNS queries.

==== The protocol ====

Current <tt>download_and_compile.sh</tt> (from December 2022) fetches the source code of most components from Git repositories (earlier versions used Subversion for some components); a few non-core components (currently [[FGo!]] and [[OpenRadar]]) are fetched using <tt>wget</tt> and are out-of-scope for this section.

The default protocol used by <tt>download_and_compile.sh</tt> when cloning a Git repository is [https://en.wikipedia.org/wiki/HTTPS HTTPS]. This can be overridden using the <tt>--git-clone-default-proto</tt> option. In other words, the default is <tt>--git-clone-default-proto=https</tt> (the protocol name is case-insensitive). Other possibilities for the protocol are <tt>git</tt> and <tt>ssh</tt>.

{{Warning|The <tt>git</tt> protocol doesn't protect against man-in-the-middle attacks; use at your own risk! Unfortunately, “clever” people often recommend it on the forum without mentioning its downsides.}}

Using the <tt>ssh</tt> protocol as the argument of <tt>--git-clone-default-proto</tt> has little use, because in general you'll want to specify a particular username when using SSH and this username is likely not to be the same for all components you intend to clone via SSH (right, <tt>~/.ssh/config</tt> can be used to automatically provide a site-dependent username). That is why <tt>download_and_compile.sh</tt> offers the <tt>--git-clone-site-params</tt> option.

==== Site-specific settings ====

Using
--git-clone-site-params ''SITE''=''PROTOCOL''[:''USERNAME'']
you can tell <tt>download_and_compile.sh</tt> that every component fetched from ''SITE'' should be cloned with the specified protocol and username (allowed protocols are <tt>https</tt>, <tt>ssh</tt> and <tt>git</tt>).

{{Note|In case you have several repositories at a given site (say, GitHub) and need to use different SSH usernames for these repositories, you can use different site names:
<pre>
--override-repo COMPONENT_A=GitHubA:ADDRESS_A
--git-clone-site-params GitHubA=ssh:userA
--override-repo COMPONENT_B=GitHubB:ADDRESS_B
--git-clone-site-params GitHubB=ssh:userB</pre>
Here, the site names are <tt>GitHubA</tt> and <tt>GitHubB</tt>; the <tt>--override-repo</tt> option will be presented below.

By default, <tt>download_and_compile.sh</tt> case-insensitively uses the <tt>GitLab</tt> (resp. <tt>SourceForge</tt>) site name to identify the settings used when cloning a repository from gitlab.com (resp. git.code.sf.net). Therefore, the settings for GitHubA and GitHubB in this example would only apply to components ''c'' for which --override-repo ''c''<nowiki>=</nowiki>GitHubA:... or --override-repo ''c''<nowiki>=</nowiki>GitHubB:... has been specified.}}

==== Component-specific settings ====

The <tt>--override-repo</tt> and <tt>--component-branch</tt> options allow one to override the default settings used by <tt>download_and_compile.sh</tt> for cloning the repository corresponding to the specified component (they only apply to components whose source code is retrieved with Git). The syntax of these options is
--override-repo ''COMPONENT''=''SITE'':''ADDRESS''
and
--component-branch ''COMPONENT''=''BRANCH''
In this syntax:
* ''COMPONENT'' represents the name of a component for <tt>download_and_compile.sh</tt> (e.g., <tt>SIMGEAR</tt>—see [[#List of available components|List of available components]]);
* ''ADDRESS'' is something like <tt>gitlab.com/flightgear/simgear.git</tt> (don't include any <tt>protocol://</tt> part in ''ADDRESS'');
* ''BRANCH'' should be the name of an existing branch of the Git repository hosted at ''ADDRESS'';
* ''SITE'' is a string used as a key in a mapping; <tt>download_and_compile.sh</tt> uses it to find out how to connect to ''ADDRESS'' in order to clone the repository for ''COMPONENT'' (see [[#Site-specific settings|Site-specific settings]]).
See the [[#A short example|above example]] for a concrete example where these options are used.

{{Note|The argument of any long option of <tt>download_and_compile.sh</tt> that takes an argument may be introduced immediately after the option name using an equal sign. However, in the above cases, I find this way a bit confusing because the option value ''also'' uses an equal sign as separator. Hence the above use of separate command arguments: one for the option name, one for its argument.}}

=== Passing custom arguments to CMake ===

Sometimes, when building a program, you may want to enable a feature that is not enabled by default, or disable a feature that is enabled by default. With recent versions of <tt>download_and_compile.sh</tt> (October 2020 or later), this can be done for SimGear and FlightGear using the <code>--sg-cmake-arg</code> and <code>--fg-cmake-arg</code> options (the environment variables <tt>SG_CMAKEARGS</tt> and <tt>FG_CMAKEARGS</tt> are still supported, but they don't allow one to pass arguments containing spaces). For instance, in order to link SimGear with the system Expat library, you can do:
$ download_and_compile.sh --sg-cmake-arg='-DSYSTEM_EXPAT=ON' SIMGEAR
Similarly, disabling HID-based input when building FlightGear can be achieved this way:
$ download_and_compile.sh --fg-cmake-arg='-DENABLE_HID_INPUT=OFF' FGFS

{{Note|Such options are typically defined in <tt>CMakeLists.txt</tt> files, for example {{simgear source
| path = CMakeLists.txt
| text = here
}} for SimGear and {{flightgear source
| path = CMakeLists.txt
| text = here
}} for FlightGear.}}

This can be useful, for instance, to work around bugs in a part of SimGear or FlightGear that you don't need, but causes a build or runtime failure (see {{forum link|t=35740|text=here}} for example). This is often convenient when using the development version of FlightGear, but doesn't mean such bugs shouldn't be reported!

If you have several such options to pass, just use <code>--sg-cmake-arg</code> and/or <code>--fg-cmake-arg</code> several times:
$ download_and_compile.sh --fg-cmake-arg='-DENABLE_SWIFT=ON' \
--fg-cmake-arg='-DENABLE_HID_INPUT=OFF' FGFS
It is even possible to pass arguments containing spaces to CMake, as in:
$ download_and_compile.sh \
--sg-cmake-arg='-DCMAKE_CXX_FLAGS=-Wno-deprecated-declarations -Wall' \
SIMGEAR
(just a silly example to show a working syntax) or:
$ download_and_compile.sh \
--fg-cmake-arg="-DCMAKE_CXX_FLAGS=$(pkg-config --cflags gl)" \
FGFS
Note the use of double-quotes here to enable the <code>$(...)</code> command substitution.

Using the (half-deprecated) environment variables <tt>SG_CMAKEARGS</tt> and <tt>FG_CMAKEARGS</tt>, it is also possible to define CMake arguments in a single place that are going to be used for both SimGear and FlightGear. However, this technique doesn't allow one to pass arguments containing spaces to CMake.
$ export SG_CMAKEARGS='-DSYSTEM_EXPAT=ON'
$ export FG_CMAKEARGS='-DENABLE_SWIFT=ON -DENABLE_HID_INPUT=OFF'
$ download_and_compile.sh

=== Seeing the compilation commands run by Make ===

As a simple application of the previous section, the following options are often useful. When passed to <tt>download_and_compile.sh</tt>, these options cause the compilation commands run via Make to be printed on the terminal and recorded in the compilation_log.txt file:
--sg-cmake-arg='-DCMAKE_VERBOSE_MAKEFILE=1' \
--fg-cmake-arg='-DCMAKE_VERBOSE_MAKEFILE=1'
(the backslash is unneeded if you put both options on the same line). Passing the value 0 instead of 1 would explicitly request the default, non-verbose behavior.

=== Launching FlightGear ===

When using <tt>download_and_compile.sh</tt>, apart from those installed with the package manager, the FlightGear dependencies (which are typically libraries) are not installed system-wide but under the directory from which <tt>download_and_compile.sh</tt> was run. This makes it possible to easily use, for instance, different [[OpenSceneGraph]], [[SimGear]] and FlightGear versions on a single system—e.g., for testing purposes—but also to have separate build trees (optimized/debug). This is also why you either need to set LD_LIBRARY_PATH to run the built programs, or simply use the scripts created by <tt>download_and_compile.sh</tt> in the directory where it is run, such as <tt>run_fgfs.sh</tt> and <tt>run_fgfs_debug.sh</tt>: these scripts automatically set up the required environment variables according to your build settings before firing the desired program (e.g., <tt>fgfs</tt>) with the arguments you provided.

Therefore, the simplest way to run a FlightGear program built by <tt>download_and_compile.sh</tt> is to launch the <tt>run_fgfs.sh</tt> script that <tt>download_and_compile.sh</tt> created in the directory from which it was run, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --launcher

{{Note|<code>./run_fgfs.sh --launcher</code> starts FlightGear with its built-in launcher. If you just do <code>./run_fgfs.sh</code>, FlightGear will be started without any launcher, at the default airport and with the default aircraft.}}

In order to start FlightGear without any launcher, at a given airport (say, [https://en.wikipedia.org/wiki/Paro_Airport Paro airport], whose ICAO code is VQPR) and with a chosen aircraft, you can do:
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --airport=VQPR --aircraft=dhc6
Actually, the directory change is not needed, we only gave it here for readability. Therefore, the following single command does the same:
$ ~/flightgear/dnc-managed/run_fgfs.sh --airport=VQPR --aircraft=dhc6

=== Avoiding multiple downloads of FGData ===

Some people use <tt>download_and_compile.sh</tt> to maintain several directory trees such as the tree starting at <tt>~/flightgear/dnc-managed</tt> in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]] (this can be useful if you want to have one tree with programs compiled in Release mode and another tree where they are built in Debug mode, for instance). This can easily be done by running <tt>download_and_compile.sh</tt> in each of the directories. But since [[FGData]] is so large, it may be tempting to share a single instance of this repository among several trees. This is not officially supported, but apparently can be made to work with symbolic links.

Let's show how this can be done on an example. Suppose your master copy of FGData is in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt>. Then the following appears to work:
$ mkdir -p ~/flightgear/other-dnc-managed-tree/install/flightgear
$ cd ~/flightgear/other-dnc-managed-tree/install/flightgear
$ ln -s ../../../dnc-managed/install/flightgear/fgdata
$ cd ~/flightgear/other-dnc-managed-tree
$ download_and_compile.sh

The last of these commands will use and update the FGData repository present in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt>.

{{Warning|This can only work simply if all trees that share a given FGData repository are from the same release (e.g., current stable or development). Running a “stable“ FlightGear with FGData from the ''next'' branch or the other way round, a development version of FlightGear with FGData from a release branch, doesn't work—and FlightGear should tell you when you start it in such a situation.

That said, people comfortable with Git can check out the correct FGData branch before building or starting FlightGear, for instance:
$ cd /path/to/fgdata && git checkout release/2019.1
or
$ cd /path/to/fgdata && git checkout next
So, this is possible but somewhat acrobatic. You've been warned.}}

Note: there is a [[Avoiding multiple downloads of FGData on Linux|wiki article about this subject]], but it is severely outdated as of April 2019.

== Additional programs ==

{{Note|In this section, we assume you've read and followed the advice given in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]].}}

If you wish to get other programs (precisely: download, build and install them), you need to launch <tt>download_and_compile.sh</tt> with the desired component names as arguments. For instance:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

See [[#list-of-available-components|above]] for the list of available components.

=== TerraGear ===

Run <tt>download_and_compile.sh</tt> with the TERRAGEAR component in order to build and install the [[TerraGear]] terrain building toolchain:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh TERRAGEAR

This creates the following scripts in <tt>~/flightgear/dnc-managed</tt>:
* <tt>run_genapts850.sh</tt>
* <tt>run_ogr-decode.sh</tt>
* <tt>run_tg-construct.sh</tt>
These scripts themselves run the corresponding TerraGear tools, as expected.

=== TerraGear GUI ===

[[TerraGear GUI]] is a graphical interface for [[TerraGear]] written with the Qt toolkit (still Qt 4 in 2019, but it works). In order to install it, run <tt>download_and_compile.sh</tt> with the TERRAGEARGUI component:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh TERRAGEARGUI
This will create a <tt>run_terrageargui.sh</tt> script in <tt>~/flightgear/dnc-managed</tt>, and also a default configuration file <tt>~/.config/TerraGear/TerraGearGUI.conf</tt>, unless you already have one. This default configuration file contains paths to the TerraGear and [[$FG_ROOT]] directories, assuming you have installed the TERRAGEAR and DATA components.

To run TerraGear GUI:
$ cd ~/flightgear/dnc-managed
$ ./run_terrageargui.sh

=== FGCom ===

{{Note|[[FGCom]] has been integrated into FlightGear long ago, therefore the following is not needed in general.}}

[[FGCom]] is the system used by FlightGear to simulate radio communications between users. It is automatically built and installed when you tell <tt>download_and_compile.sh</tt> to take care of the FGFS component. You can launch the standalone FGCom program by using the <tt>run_fgcom.sh</tt> script:
$ cd ~/flightgear/dnc-managed
$ ./run_fgcom.sh

=== FGRun ===

{{Note|As of 2019, FGRun has been superseded by the [[FlightGear Qt launcher|FlightGear built-in launcher]]. The built-in launcher is the most actively maintained launcher for FlightGear. Other launchers are [[FFGo]] and [[FGX|FGx]].}}

[[File:fgrun-page2.jpg|thumb|right]]
Before FlightGear had its built-in launcher (the one you get with <code>run_fgfs.sh --launcher</code>), many users found comfortable having FlightGear launched by the graphical utility [[Fgrun|FGRun]]. This program is built and installed when <tt>download_and_compile.sh</tt> is run with the FGRUN component. You then have to launch the <tt>run_fgrun.sh</tt> command, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgrun.sh

FGRun will save its settings in <tt>~/.fltk/flightgear.org/fgrun.prefs</tt>. You may want to save copies of the preferences customized for stable and next.

=== FGo! ===

{{Note|As of 2019, FGo! is not maintained anymore. You may want to try the built-in launcher (started with <code>run_fgfs.sh --launcher</code>) or [[FFGo]].}}

[[File:Fgo01.jpg|thumb|left]]
FGo! is a graphical utility written in [[python]]. It is downloaded and installed when <tt>download_and_compile.sh</tt> is run with the FGO component. You then have to launch the <tt>run_fgo.sh</tt> command, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgo.sh

Remember that the first time you run it, you have to go to open the ''Preferences'' dialog and set the paths to the <tt>fgfs</tt> executable and to FGData.

== Troubleshooting ==

=== Compilation errors ===
Here we are, no fear, if you wish to use programs from the cvs/svn/git repositories, you might face compilation errors that will prevent you to have a working copy of one or more of the programs provided by this script. What can be the causes that prevent us from successfully compiling? As far as I know those:
# Software developers introduce a new functionality with a new piece of code that prevents the compilation under your architecture, this can happen working with cvs/svn/git sources.
# The program refuses to compile because of a divergence in the libraries on which it depends. For example FlightGear might not compile because OSG has been modified, while OSG itself compiles fine, FG won't.
# One or more repositories are down and you can't get the library you need. (Both from cvs/svn/git or apt-get)

There is a simple solution to the above errors: wait and relaunch the script after some time (hours or days), if software developers repair or synchronize their code with the newly updated libraries (which generally happens eventually), your FlightGear will compile fine as if the previous error never took place.

Sometimes it happens that the script fails to compile only [[Fgrun|FGRun]], [[FGCom]] or atlas, if you then see the run_fgfs.sh file it means that FlightGear installation was successful and you can safely run it.

== Options ==

=== Release selection ===

* Build the latest stable release: <code>-s</code>
* Build the latest Long Term Stable release: <code>--lts</code>
* Build the previous Long Term Stable release: <code>--old-lts</code>

Long Term Stable (<code>--lts</code>) is supposed to yield a more stable setup than what you would obtain with option <code>-s</code>, however it will generally be older. Both of these options are suitable for users.

If you pass none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> in a <tt>download_and_compile.sh</tt> invocation, you'll build the the ''next'' suite, which contains the development version of FlightGear. The corresponding FlightGear code will be very recent but may well be unstable—this is particularly the case starting from July 2020. This is therefore mostly intended for developers.

=== Skipping most prompts ===

For some important things, <tt>download_and_compile.sh</tt> asks for confirmation in order to be sure that you are well informed about what will be done. When you have a good understanding of these informations, you may want to use the <code>--non-interactive</code> option in order to suppress these prompts (technically, this causes the default answer to be automatically used).

=== Cleaning built and installed files ===

Option <code>--cleanup</code> causes <tt>download_and_compile.sh</tt> to remove everything that was built and installed in the directory it is run from. The Git repositories will not be removed, so this is good if you want to restart a compilation from a clean state.

If you use <code>--cleanup</code> without specifying any component, only this removal will be done (nothing will be compiled nor installed). Otherwise, the usual rules concerning components apply.

=== Multicore acceleration ===

Passing option <code>-j x</code> to <tt>download_and_compile.sh</tt> (where ''x'' is the number of your CPU cores you wish to assign to the job) will considerably speed up the compilation steps. Passing <code>-j$(nproc)</code> is a convenient way to automatically use all available cores.

=== Advanced options ===

* Build a release version: <code>-b Release</code>
* Build a version that should run as fast as a release build, yet has debug information that can be used to post backtraces: <code>-b RelWithDebInfo</code> (this is the default)
* Build a full debug version for very complete bug reporting: <code>-b Debug</code>
* Skip download of distro packages (i.e., by default: <tt>apt-get install ...</tt>): <code>-p n</code>
* Skip retrieving of component downloads and updates (which typically use Git or wget): <code>-d n</code>
* Skip the configure step (like running [https://cmake.org/ CMake] or [https://www.gnu.org/software/autoconf/ autoconf]'s <tt>./configure</tt>): <code>-r n</code>
* Skip compilation of programs: <code>-c n</code>
* Build with compositor: <code>--compositor</code>
* Force the use of a particular branch for a given component: <code>--component-branch ''COMPONENT=BRANCH''</code> (e.g., <code>--component-branch OSG=OpenSceneGraph-3.6</code>, <code>--component-branch FGFS=next</code>, etc.—but remember that components FGFS, SIMGEAR and DATA must ''always'' be in sync). See [[#Component-specific settings|Component-specific settings]] for details.
* Override the repository from which a given component is initially fetched: <code>--override-repo ''COMPONENT''=''SITE'':''ADDRESS''</code> (see [[#Component-specific settings|Component-specific settings]]).
* Generate build.ninja files and build using Ninja: <code>-G Ninja</code>
* Run CMake in verbose mode: <code>--verbose</code> (this shows compilation commands)

For example, if you are a developer and wish to quickly recompile and reinstall only your own modifications for FlightGear, you can do this:
$ download_and_compile.sh -j$(nproc) -p n -d n -r n FGFS

Note that this is the same as:
$ download_and_compile.sh -j$(nproc) -pn -dn -rn FGFS

This command will only rebuild modified files and reinstall FlightGear. Note that depending on the kind of changes you made, reconfiguring and thus dropping the <code>-rn</code> option may be necessary, though (this is the case in particular if you added or removed C++ files).

=== ccache ===
[https://ccache.dev/ ccache] is a compiler cache that enormously speeds up subsequent recompilations (compilation times are often divided by a factor 6 or more). SimGear and FlightGear 2024.1 or later perform <tt>ccache</tt>-enabled builds when <code>-DENABLE_CCACHE=ON</code> is passed to [https://cmake.org/ CMake]. For <tt>download_and_compile.sh</tt> users, there are several ways to do this.

The simplest way is to pass <code>--enable-ccache</code> to <tt>download_and_compile.sh</tt>. This has an effect when processing components such as <tt>SIMGEAR</tt> and <tt>FGFS</tt>; other components may support the option or ignore it. Using this option is equivalent to passing <code>--cmake-arg ALL="-DENABLE_CCACHE=ON"</code> to <tt>download_and_compile.sh</tt>. This causes the script to pass <code>-DENABLE_CCACHE=ON</code> to all CMake-based components that are processed. For those that don't support this option, you'll see a harmless warning that you can safely ignore:

<pre>
CMake Warning:
Manually-specified variables were not used by the project:

ENABLE_CCACHE
</pre>

Finally, if you prefer, you can pass <code>-DENABLE_CCACHE=ON</code> to specific components using for instance
--cmake-arg SIMGEAR="-DENABLE_CCACHE=ON"
and/or
--cmake-arg FGFS="-DENABLE_CCACHE=ON"
This results in longer command lines than the previous methods but allows one to avoid the warning, if it bothers you.

{{Note|<tt>download_and_compile.sh</tt> automatically installs <tt>ccache</tt> if its seems required and package installation hasn't been disabled. Otherwise, you can install it yourself using <code>apt install ccache</code> before using <code>--enable-ccache</code> or similar.}}

== Optimus technology ==
If your computer has a GPU with Optimus technology, you need a dedicated script in order to make FlightGear run with the powerful GPU.

After having installed required tools (Bumblebee) you just need to run this command line in your FlightGear installation directory (where you executed <tt>download_and_compile.sh</tt>):
$ sed 's|\./fgfs|optirun ./fgfs|' run_fgfs.sh > run_fgfs_optirun.sh && chmod +x run_fgfs_optirun.sh
Now you can run FlightGear with <code>./run_fgfs_optirun.sh</code>.

The same can be done for the [[FlightGear_Launch_Control|FGRun]] launcher:
$ sed 's|\./fgrun|optirun ./fgrun|' run_fgrun.sh > run_fgrun_optirun.sh && chmod +x run_fgrun_optirun.sh

== See also ==

* {{fgmeta source
| path = fg-from-scratch
| text = fg-from-scratch
}};
* [[Fedora Packages and Compiling]];
* [[Superbuild]];
* [http://geoffmclane.com/fg/fgfs-052.htm Another script] for building FlightGear and all its dependencies in an automated fashion. The page seems a bit oldish, though (as of 2019).

== References ==
<references/>

[[Category:Building from source]]

[[fr:Script de compilation sous Linux Debian/Ubuntu]]
[[nl:Compileren met een Script op Linux Debian/Ubuntu]]

FlightGear wiki:Village pump

2026-04-21T13:40:14Z

Rominet: /* Nasal unit test assertion documentation */ Add signature

__NEWSECTIONLINK__
{{Archives|[[/Archive 2012|2012]]|[[/Archive 2013|2013]]|[[/Archive 2014|2014]]|[[/Archive 2015|2015]]|[[/Archive 2016|2016]]|[[/Archive 2017|2017]]|[[/Archive 2018|2018]]|[[/Archive 2019|2019]]|[[/Archive 2020|2020]]|[[/Archive 2021|2021]]|[[/Archive 2022|2022]]}}
{{shortcut|FGW:VP}}

Welcome to the '''Village Pump'''. This page is used to discuss the technical issues, operations and guidelines of the [[FlightGear wiki]].

Please [{{fullurl:{{FULLPAGENAME}}|action=edit&section=new}} add new topics] to the '''bottom''' of this page.

Old discussions should be moved to a [[FlightGear wiki:Village pump/Archive YEAR]]. These discussions can then be moved to a relevant talk page if appropriate.

__TOC__

== MediaWiki updated to 1.39.6 ==

We have updated MediaWiki to its latest LTS version 1.39.6 today. Although we've tested the update, chances are that we've missed certain scenarios or features. Please report any issues that you may encounter.

[[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 09:31, 30 January 2024 (UTC)

== Embedded YouTube videos broken ==

It seems that the [[mw:Extension:EmbedVideo|EmbedVideo extension]] was removed at some point. Consequently, pages such as [[Howto:Creating FlightGear Promo Videos]] are broken. At present, the best replacements seems to be [[mw:Extension:EmbedVideo_(fork)|a fork]] and [[mw:Extension:YouTube|Extension:YouTube]].

—'''''[[User:Red Leader|Red Leader]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 19:21, 30 January 2024 (UTC)

: Hi,
: Thanks for the report. It was introduced by today's update, but should be fixed now.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 21:21, 30 January 2024 (UTC)

:: Confirmed, thanks. And I’d completely forgotten about {{[[Template:Wikipedia|wikipedia]]}}. 😅
:: '''''[[User:Red Leader|Red Leader]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 21:57, 30 January 2024 (UTC)

== Forum registration problem ==

Hello,
I would like to register on the forum, but I tried several times without success. I sent an email to the administrator some time ago, but it seems to have been lost. I don't know what to do, is there somebody here who could help? Please tell me if you need additional information.
Thanks very much in advance. [[User:Kestrel|Kestrel]] ([[User talk:Kestrel|talk]]) 13:14, 25 March 2024 (UTC)

: Hi,
: That's unfortunate! You can find my email address at https://forum.flightgear.org/contact.php Please try again if you've done that before, I'll actively monitor the address for any incoming messages, and let me know if you don't get a reply.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 15:01, 25 March 2024 (UTC) (forum admin)

== Sidebar link for "Build server" is broken ==

Hello,

Just wanted to bring to someones attention that the URL for "Build server" currently 404s. Not sure if this resource still exists or if its URL has changed.

Cheers!
-Joshua

: Hi Joshua,
: The URL is still correct, but the build server is temporarily down due to a server failure. It's being worked on, so should be back up "soon".
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 12:29, 3 September 2024 (UTC)

== FlightGear Wikipedia article image needs correctly sourced Flightgear wiki screenshot ==
https://en.wikipedia.org/wiki/FlightGear

The image used for the Flightgear Wikipedia article appears to have been deleted, because it was sourced from the following Flightgear-wiki screenshot page:

[[:File:Bo 105 over Sint Marteen.png]]

which referred to an imgur link instead of the following thread, which gives a CC license based on a google search of the file name:

https://forum.flightgear.org/viewtopic.php?f=88&t=32163&start=0

Discussion on Wikipedia:

https://en.wikipedia.org/wiki/Wikipedia:Files_for_discussion/2024_December_7#File:FlightGear_Flight_Sim_Bo_105_over_Sint_Marteen.png

> ''Subsequent comments should be made on the appropriate discussion page (such as the file's talk page or in a [https://en.wikipedia.org/wiki/Wikipedia:Deletion_review deletion review]).''

The person who uploaded it, or someone from the wiki, should ideally fix the FlightGear wiki page, and do a deletion review for the Wikipedia file. The file may have been used in multiple pages since screenshots are uncommon on Wikipedia due to proprietary apps. Feel free to remove this comment once it's taken care of. Good luck

== Issues with three templates ==

Hi,

The [[Template:Fgmeta_commit|fgmeta commit]] template appears to be broken. It used to work in the first ''Note'' [[Scripted_Compilation_on_Linux_Debian/Ubuntu#For_the_curious:_the_SSH_way|here]] (see the URL).

Also, I tried to use [[Template:Repo_link#Site:_Generic]] to create a link to the [https://gitlab.kitware.com/cmake/cmake.git CMake repo], but didn't manage: IIRC, the link text was empty.

Finally, [[Template:Fgmeta_source]] doesn't seem to to what the doc. says for ''simplepath'': with
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| simplepath = 1
}}</nowiki></pre>

the link text starts with a slash, so I used
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| text = download_and_compile.sh
}}</nowiki></pre>
which is of course more redundant.

Thanks for considering! :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: Good catch. I need to look into that one. I may not have coded the commit part of GitLab into the master {{tl|repo_link}} template.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:41, 13 March 2025 (UTC)

:: All fixed. It was quite simple - the {{tl|fgmeta_source}} template was missing the <code>proj</code> parameter. I've also fixed {{tl|fgmeta_clone}}.

:: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:53, 13 March 2025 (UTC)

::: Thanks for the reply and fixes, Bugman! (And sorry for the delay, I didn't see any notification...) I see the first item is indeed addressed. Regarding the second item, well, I see no place where I'd really want to use this now on the d&c page, so didn't test it. As for the third one, I still get <code>/download_and_compile.sh</code> in the Preview when I try the above {{tl|fgmeta_source}} snippet with <code>simplepath = 1</code>.

::: I looked at {{tl|fgmeta_clone}} too; it looks nice but seems to default to the <code>git://</code> protocol. Would it be possible to make it default to using <code>https://</code>? Thanks again. :-)

::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

:::: Not a problem. For the <code>simplepath</code> parameter, that is the designed behaviour in the {{tl|repo link}} template. In most cases our repositories have complex directory structures and the desired output is the absolute file path, removing the protocol and URL parts of the path. Do you wish to simply have the file name there? No one had asked for that before, so I never added an option for that. In the case of the source repositories, you often want to remove the first part of the absolute path so that for example in SimGear, {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}}</nowiki>) would be shown as {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}}</nowiki>. This is not scriptable in MediaWiki so I left it all for the text parameter.

:::: For the protocol, I have now added the <code>protocol</code> parameter. E.g. <nowiki>{{fgmeta clone | protocol = https}}</nowiki>. That will give <code>{{fgmeta clone | protocol = https}}</code> (as of today generated as <code><nowiki>git clone https://gitlab.com/flightgear/fgmeta.git</nowiki></code>).

:::: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 08:51, 24 March 2025 (UTC)

::::: Thanks Bugman, I've updated the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] to use <code><nowiki>{{fgmeta clone | protocol = https}}</nowiki></code> as you proposed; it works great. For the link to download_and_compile.sh, I can continue to use <code><nowiki>{{fgmeta source | path = download_and_compile.sh | text = download_and_compile.sh}}</nowiki></code>, no problem.

::::: As far as I'm concerned, everything is resolved here, so this thread/section can be deleted if someone wants to “clean up”.

::::: ''Other subject:'' the only remaining thing is that I didn't receive any notification, neither for your replies here nor for the January changes by [[User:Jebba|Jebba]] to the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] that is on my watchlist. I used to receive email notifications for these things years ago, haven't changed my preferences regarding this and don't see any setting that would explain why I don't receive these notifications anymore. Maybe email sending by the wiki software is not quite well configured according to current standards (SPF, DKIM, DMARC)?

::::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Improve the 'simgear clone', 'flightgear clone' and 'fgdata clone' templates ==

Hi,

In order to improve [[Fedora_Packages_and_Compiling]], it would be nice to have the <code><nowiki>{{simgear clone}}</nowiki></code>, <code><nowiki>{{flightgear clone}}</nowiki></code> and <code><nowiki>{{fgdata clone}}</nowiki></code> templates on par with <code><nowiki>{{fgmeta clone}}</nowiki></code> (support for the <code>protocol</code> parameter, etc.). I tried

<nowiki>{{simgear clone | protocol = https | opt = --single-branch --branch release/2024.1 | post = simgear}}</nowiki>

but it doesn't seem to work, as the preview shows this:

<nowiki>git clone --single-branch --branch release/2024.1 git://gitlab.com simgear</nowiki>

(ditto with <code>flightear clone</code> and <code>fgdata clone</code>). Thanks in advance :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: I needed a while to work out the best strategy for these changes. I've now gone through all of the {{tl|repo link}} cloning subtemplates listed on {{tl|repo link/doc related}} and added the <code>project</code> parameter to the templates and the optional <code>protocol</code> parameter. These changes were required as the <code>gl</code> section of the {{tl|repo_link}} template is constructed differently to the <code>sf</code> section. I've also updated the git cloning documentation {{tl|repo link/doc git clone}}. I hope this covers everything you need.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 07:48, 1 April 2025 (UTC)

:: Thanks a lot, Bugman, this works great! Your changes allowed me to perform [https://wiki.flightgear.org/w/index.php?title=Fedora_Packages_and_Compiling&type=revision&diff=141687&oldid=141513 this edit] in [[Fedora_Packages_and_Compiling]]. The only remaining <code>git clone</code> command written in full on that page is for FG's fork of OpenSceneGraph at GitLab. I understand that choosing a proper name for an applicable <code><nowiki>{{... clone}}</nowiki></code> template probably requires some careful thinking... ;-)

:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Default text in Template:Repo link ==

Hi,

The default ''text'' in {{tl|Repo link}} gives somewhat pleasant link texts such as
flightgear/flightgear/src/Scripting/NasalSys.cxx
when the ''site'' is <code>sourceforge</code>, however the result looks like a bug for other sites (though I understand this may be as intended). To be clear, the URLs are correct but the default link texts look weird because they start with the unqualified site name rather than the fully-qualified domain name. For instance,
{{obr}}fgmeta source{{cbr}}
yields [https://gitlab.com/flightgear/fgmeta gitlab/flightgear/fgmeta/next] rather than [https://gitlab.com/flightgear/fgmeta gitlab.com/flightgear/fgmeta/next]. I suggest to replace <code>gitlab</code> with <code>gitlab.com</code> in the default text (where the HTML comment says “Site advertising”) and do the same for <code>github</code>.

Note: the Gitorious web site doesn't exist anymore, maybe that should be removed from the template?

Thanks for considering; I can do the replacement if you wish.

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 10:38, 12 November 2025 (UTC)

: Sounds sensible, so please go ahead!
: Regarding Gitorious, it may be nice to link to an archived version of the repos, such as https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://gitorious.org/flightgear/fgdata.git&visit_type=git Altough this only makes sense for repos or branches that are not part of our current GitLab...
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 13:58, 12 November 2025 (UTC)

:: [https://wiki.flightgear.org/w/index.php?title=Template:Repo_link&action=history Done], thanks Gijs!
::

:: One should be careful using this, though, because the resulting link ''texts'' may be non-existing URLs (after prepending the protocol) despite looking like valid ones, as shown by the first example in [[User:Rominet/Sandbox#FGMeta-Python repo templates]]!

:: So, to avoid people getting trapped by this, maybe the default link text should start with something like <code>[GitLab]/...</code> rather than the <code>gitlab.com/...</code> I just put (to make it clear that such link texts are not supposed to be “Internet addresses”).
:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 16:20, 12 November 2025 (UTC)

::: This is now implemented. For instance, <code>{{obr}}fgmeta-python source {{!}} path = pyproject.toml {{!}} tag = 1.0.0b1 {{cbr}}</code> results in {{fgmeta-python source | path = pyproject.toml | tag = 1.0.0b1 }}. This also holds for GitHub and GitoriousIsNowClosed. SourceForge has no such prefix for now (it initially didn't, and editing its part of {{tl|Repo link}} requires a bit more temerity than what I have at the moment :-)).
::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 09:15, 14 November 2025 (UTC)

: That's a good idea. Note for Gitorious - I added this because there are a number of historical documents/pages that refer to developments that occurred on Gitorious which were not migrated to SourceForge. I originally made the Gitorious links work by pointing to the archive by the Internet Archive (see [[Gitorious]]). However that archive has been offline for a few years now. The Internet Archive are storing all the data so it may return one day.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 22:06, 13 November 2025 (UTC)

== Beware of shortened Git commit IDs ==

While fixing broken links due to the {{tl|foo commit}} templates not specifying <code>proj=flightgear</code> (this was implicit with <code>site=sf</code> but isn't with <code>site=gl</code>), I found that URLs at GitLab don't accept the same shortened Git commit IDs as those at SourceForge:
https://sourceforge.net/p/flightgear/fgdata/ci/807062 - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062 - NOK
https://gitlab.com/flightgear/fgdata/-/commit/807062d - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062d0b6f858885547f27325e829c2bf42a12b - OK

As a consequence, there are probably a lot of broken links in the wiki due to shortened commit IDs. Better always use the long ones...

{{Note|Commit ID 807062 in FGData is not ambiguous at the time of this writing.}}
[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 15:45, 3 December 2025 (UTC)

: I have modified {{tl|Simgear_commit}}, {{tl|Flightgear_commit}}, {{tl|Fgdata_commit}}, etc. (12 templates!) to show a commit ID truncated to 7 characters in the automatically generated link text, so there is no excuse for not using the full commit IDs anymore when using these templates (see the result [[Howto:Building_FlightGear_without_HiDPI_support#Commits|here]] for instance). Thanks to [[User:Gijs|Gijs]] for installing [https://en.wikipedia.org/wiki/Module:Ustring Module:Ustring] which made this possible!

: Note that manually provided ''text'' arguments are not truncated.
: {{tip|In case you feel like replacing shortened commit IDs with full ones in {{tl|foo commit}} template calls, the full commit IDs can be found like so:
cd /path/to/repository
git rev-parse ''shortened-id1'' ''shortened-id2'' ...
}}

: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 18:05, 25 December 2025 (UTC)

== Nasal unit test assertion documentation ==
I just started an article about [[Nasal unit tests]] but could need some help improving the section about the tests.

The only documentation I find is the {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx|text=C++ source code}} and the existing test files (<code>test_*.nut</code>) in {{fgdata source|path=Nasal|text=fgdata/Nasal}} (side note: it took me several days to figure out where the <code>nasal-test</code> FGCommand was implemented).

—[[User:Johan G|Johan G]] ([[User_talk:Johan_G|Talk]] | [[Special:Contributions/Johan_G|contribs]]) 12:36, 14 March 2026 (UTC)

: In order to find the <code>nasal-test</code> FGCommand, a simple approach is to run, in the three main repositories, <code>git grep -Fe nasal-test</code> (or, more accurately but slower: <code>git grep -Ee '\bnasal-test\b'</code>). This shows a few lines including
globals->get_commands()->addCommand("nasal-test", &command_executeNasalTest);
: which indicates that the command is implemented by {{flightgear source | path=src/Scripting/NasalUnitTesting.cxx | line=148 | text=command_executeNasalTest()}}, which can be found using either IDE-like features (LSP server, etc.) or the same <code>git grep</code> technique. :-)

: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 13:40, 21 April 2026 (UTC)

FlightGear wiki:Village pump

2026-04-19T13:55:42Z

Rominet: /* Nasal unit test assertion documentation */ How to find where an FGCommand is implemented

Talk:Nasal unit tests

2026-04-19T13:38:46Z

Rominet: Nasal unit tests don't use the .nut extension anymore

== Nasal unit tests renamed from <code><foo>.nut</code> to <code>test_<foo>.nas</code> ==

See https://gitlab.com/flightgear/flightgear/-/work_items/3127 and the corresponding commits:
* {{flightgear commit | 6488bff546d062c756a0cc13ba7572e2d5f5f50e}};
* {{fgdata commit | 8bd5c738e401a963ec7ecddc636fb86915cd1199}}.

Scripted Compilation on Linux Debian/Ubuntu

2026-04-19T13:16:47Z

Rominet: /* ccache */ Update the whole section

<tt>download_and_compile.sh</tt> is a Bash script that takes care of downloading and compiling FlightGear and related software from their source code repositories with just one command execution for both 32-bit and 64-bit [https://www.debian.org/ Debian]-based systems. Pre-existing versions (if any) of the software installed by <tt>download_and_compile.sh</tt> are not touched at all since the script downloads, builds and installs everything under the directory in which it is launched. You can choose the particular components to download, build and install.

Unless told not to do so, <tt>download_and_compile.sh</tt> installs packages with <tt>apt-get</tt>. For this reason, it is primarily useful on Debian-based distributions. However, if one disables package installation (using <code>-pn</code> or <code>--sudo=echo</code>) and installs the corresponding dependencies oneself, it can be used on other Unix-like systems such as [https://fedoraproject.org/ Fedora Linux], [https://archlinux.org/ Arch Linux] or [https://www.openbsd.org/ OpenBSD].

== Introduction ==

<tt>download_and_compile.sh</tt> is a [https://www.gnu.org/software/bash/ Bash] script written for [https://www.debian.org/ Debian]-derived distributions ([https://www.ubuntu.com/ Ubuntu], [https://devuan.org/ Devuan], [https://www.linuxmint.com/ Linux Mint], etc.). Its purpose is to automatically install dependencies using the package manager, then build and install FlightGear-related programs.

By default, <tt>download_and_compile.sh</tt> installs most dependencies with <tt>apt-get</tt> run under <tt>sudo</tt>.<ref name="disabling-installation-of-dependencies-via-package-manager">If you think you already have the dependencies, this installation can be disabled either by using option <code>-pn</code> or by passing option <code>--sudo=echo</code> (the latter results in printing the <tt>apt-get</tt> command line without running it).</ref> Other dependencies, either because they aren't available in the standard APT repositories, or because of non-option arguments passed to <tt>download_and_compile.sh</tt>, are downloaded and compiled on the fly (this can be the case for [[PLIB]], [[Simgear]] and [[OpenSceneGraph]], for instance—it all depends on the arguments passed to the script).

<tt>download_and_compile.sh</tt> works in the directory it is run from: apart from dependencies installed via the package manager, all programs built by <tt>download_and_compile.sh</tt> are installed under the <tt>install</tt> subdirectory of the directory from which the script was run. In other words, installation of programs by <tt>download_and_compile.sh</tt> is clean, very easy to undo and doesn't interfere with other programs on the system.

It is possible to manage several directory trees with <tt>download_and_compile.sh</tt>; as far as it is concerned, such directory trees are completely independent from each other. For instance, if you run <tt>download_and_compile.sh</tt> in <tt>dir1</tt> and <tt>dir2</tt>, the programs installed under <tt>dir1</tt> won't “see” those installed under <tt>dir2</tt>, and vice versa.

Apart from its main purpose, <tt>download_and_compile.sh</tt> can be used to find hopefully up-to-date build-dependency information for FlightGear and related software. You would do so by inspecting {{fgmeta source
| path = download_and_compile.sh
| text = the script
}} at the point where it installs packages.<ref name="note-inspecting-download-and-compile-sh-to-gather-build-dependency-information">Look for strings such as <tt>zlib1g-dev</tt>, <tt>libglew-dev</tt> or <tt>qt5-default</tt>.</ref>

== Prerequisites ==

Before embarking on building your own FlightGear binaries, you need to install a few tools that <tt>download_and_compile.sh</tt> uses to retrieve and compile source code. These tools are found in the following packages on [https://www.debian.org/ Debian] systems (and presumably on most Debian derivatives too):

* build-essential
* git
* cmake

These packages can be installed by running a command such as:
$ sudo apt-get install build-essential git cmake
Once this is done, the <tt>download_and_compile.sh</tt> script can be run. Unless told otherwise, it will install additional tools and libraries as it runs, depending on the chosen components (this will be explained in further sections).

== Disk space requirements and build time ==

As of April 2019, building FlightGear requires about 12 [https://en.wikipedia.org/wiki/Gibibyte GiB] of disk space. Note that this includes downloaded source code for [[SimGear]] and FlightGear, generated build files and the large [[FGData]] repository (about 6 GiB for that one).

With an Intel Core i7 860 CPU (2.80 GHz) purchased in 2009, compiling [[SimGear]] and FlightGear 2019.2 with option <code>-j8</code> takes about 14 minutes. If you don't have a fast machine and build using only one core, it may require several hours.

== Download ==

You can get <tt>download_and_compile.sh</tt> {{fgmeta source
| path = download_and_compile.sh
| text = from FGMeta
}}. It is contained in the [[FGMeta]] repository, which is maintained by the FlightGear developers. The script can be downloaded from the link given above, however, for easier updates and in order to have the command <code>download_and_compile.sh --version</code> work as intended, it is recommended to get it as explained [[#getting-download-and-compile-sh-using-an-fgmeta-clone|below]].

In case you build stable versions of FlightGear using either of the <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> options of <tt>download_and_compile.sh</tt>, remember to update the script before trying to build a new version of FlightGear (see [[#updating-download-and-compile-sh-using-an-fgmeta-clone|Updating <tt>download_and_compile.sh</tt>]] below). Of course, you can update it more often in order to benefit from new features or bug fixes; this is especially useful if you are building ''next''—that is, the development branch of FlightGear.

== Getting started with <tt>download_and_compile.sh</tt> ==

=== For the impatient ===

So, you're in a hurry, want to build FlightGear but don't want to read any explanation? You can try what follows, but be aware that you may need to come back and read part of the the following sections if you encounter a problem. All commands should be run under a normal user account; however, unless you pass option <code>-pn</code> or something similar to disable installation of packages from your distribution, you'll be asked for your <tt>sudo</tt> password during execution of the <tt>download_and_compile.sh</tt> command (<tt>sudo</tt> is used by <tt>download_and_compile.sh</tt> to run commands like <tt>apt-get</tt>). So, here is your quick recipe for getting <tt>download_and_compile.sh</tt> and using it to build FlightGear:
mkdir -p ~/flightgear/dnc-managed
cd ~/flightgear
{{fgmeta clone | protocol = https}}
cd ~/flightgear/dnc-managed
~/flightgear/fgmeta/download_and_compile.sh -s -j$(nproc)
./run_fgfs.sh --launcher

The <code>-s</code> option passed to <tt>download_and_compile.sh</tt> instructs it to build the latest stable release of FlightGear. Use option <code>--lts</code> instead if you want the latest Long Term Stable release (it may be older but possibly more stable), or <code>--old-lts</code> for the previous LTS release. If you pass none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, <tt>download_and_compile.sh</tt> will build the ''next'' suite, which contains the development version of FlightGear. For more details on these options, see [[#Release selection|Release selection]].

The command <tt>run_fgfs.sh --launcher</tt> starts the [[FlightGear Qt launcher|FlightGear built-in launcher]]. This is often convenient but not compulsory. Another way to start FlightGear could be <code>./run_fgfs.sh --airport=PHTO --aircraft=c172p</code>. There are plenty of other options, which are listed by <code>./run_fgfs.sh --help --verbose</code>.

In some cases, <tt>download_and_compile.sh</tt> stops and waits for your answer before continuing. This is done when there is something important that you should know. When you are used to these prompts and would rather not see them anymore, pass the <code>--non-interactive</code> option to suppress them.

More detailed instructions are given below. The following sections also explain how to update <tt>download_and_compile.sh</tt> and FlightGear.

=== Notations ===

When a command should be run as an unpriviledged user, it will be preceded by a dollar sign:
$ whoami
toto
In contrast, a hash sign (#) means that the command must be run with superuser privileges to achieve the desired effect:
# whoami
root

In order to make instructions easy to understand, two directories (= folders) will be consistently used for the same purpose below:
* <tt>~/flightgear/fgmeta</tt> will contain a clone of the [[FGMeta]] repository; therefore, <tt>download_and_compile.sh</tt> will reside in that directory;
* <tt>~/flightgear/dnc-managed</tt> will be the directory from which we run <tt>download_and_compile.sh</tt>. In other words, with this setup, a typical sequence of commands could be:
$ cd ~/flightgear/dnc-managed
$ ~/flightgear/fgmeta/download_and_compile.sh
or
$ cd ~/flightgear/dnc-managed
$ ~/flightgear/fgmeta/download_and_compile.sh CARES PLIB SIMGEAR FGFS DATA OSG
These are of course just examples. The aforementioned paths are not hardwired anywhere in the script; you are free to choose the directories you want for these purposes.

=== Getting <tt>download_and_compile.sh</tt> the “right way” ===

There are several ways to obtain {{fgmeta source
| path = download_and_compile.sh
| text = download_and_compile.sh
}}. The method described here makes it very easy to update the script and causes the command <code>download_and_compile.sh --version</code> to work as intended.

As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we want to clone the [[FGMeta]] repository in <tt>~/flightgear/fgmeta</tt> and work with its ''next'' branch. Let's go:
$ mkdir -p ~/flightgear
$ cd ~/flightgear
$ {{fgmeta clone | protocol = https}}
You now have a fresh FGMeta clone in <tt>~/flightgear/fgmeta</tt> and your brand new <tt>download_and_compile.sh</tt> script is located in that directory. You can already try it to see the available options:
<pre>$ ~/flightgear/fgmeta/download_and_compile.sh --help
download_and_compile.sh [OPTION...] [--] [COMPONENT...]
Download and compile components belonging to the FlightGear ecosystem.

Without any COMPONENT listed, or if ALL is specified, recompile all
components listed in the WHATTOBUILDALL variable. Each COMPONENT may
be one of the following words:

ALL, ATCPIE, CARES, CMAKE, DATA, FFGO, FGFS, FGRUN, FGX, OPENRADAR, OPENRTI, OSG, PLIB, SIMGEAR, TERRAGEAR, TERRAGEARGUI, ZLIB.

Available options:
-h, --help show this help message and exit
--version print version and license information, then exit

(...)</pre>

=== Updating <tt>download_and_compile.sh</tt> ===

Now that you have <tt>download_and_compile.sh</tt> from the [[FGMeta]] repository, it is very easy to update (this assumes you didn't modify anything yourself inside <tt>~/flightgear/fgmeta</tt>!):
$ cd ~/flightgear/fgmeta && git pull

If you want to keep updates as easy as we just showed, it is best not to modify <tt>download_and_compile.sh</tt> yourself. <tt>download_and_compile.sh</tt> has plenty of options that usually make it unnecessary to modify the script. Just run <code>download_and_compile.sh --help</code> and learn about the available options when you feel the need to change something. Unless you have special needs that can only be accomodated by modifying <tt>download_and_compile.sh</tt>, you are invited to skip to the next section.

If you really, ''really'' want to modify <tt>download_and_compile.sh</tt> while keeping updates easy, a good technique is to add your changes to your FGMeta clone in the form of one or more Git ''commits'' (no need to push them anywhere, commits can remain in your clone). How to do that is beyond the scope of this document, though; read Git tutorials if you want to learn it (there are plenty on the Internet). Once you have committed your changes to your FGMeta clone, make sure the repository is clean (use <code>git status</code>), then update it with:
$ cd ~/flightgear/fgmeta && git pull --rebase
This will apply your commits on top of the latest commit of the branch that is currently checked out, which so far contained the official version of <tt>download_and_compile.sh</tt>. In case your changes conflict with the update, Git will tell you and you'll have to resolve the conflict manually (look for “Git resolve conflict” on your favorite search engine)... or start again from a pristine [[FGMeta]] clone.

=== Building FlightGear ===

In what follows, we won't give the full path to <tt>download_and_compile.sh</tt> when showing commands to be run, but you should prepend it to <tt>download_and_compile.sh</tt> whenever you see a <tt>download_and_compile.sh</tt> command. For instance, if you used the same path as in [[#getting-started-with-download-and-compile-sh-notations|Notations]] and see the command:
$ download_and_compile.sh --help
what you should actually run is:
$ ~/flightgear/fgmeta/download_and_compile.sh --help

Apart from this harmless command, ''do not'' run other <tt>download_and_compile.sh</tt> commands from an arbitrary directory, in particular ''don't'' run them from <tt>~/flightgear/fgmeta</tt>. This is because '''most other <tt>download_and_compile.sh</tt> commands write to the current directory''' (<code>download_and_compile.sh --help</code> and <code>download_and_compile.sh --version</code> are safe to run from any directory, though).

Of course, it is always possible to make commands shorter by setting up aliases (see tips at the end of [https://sourceforge.net/p/flightgear/mailman/message/36634426/ this message]), by adding the directory containing <tt>download_and_compile.sh</tt> to your <tt>PATH</tt> or by creating a symbolink link pointing to <tt>download_and_compile.sh</tt> in a directory that is part of your <tt>PATH</tt>. This is not necessary, though; do it only if you feel the need (when enabled, persistent shell history is often enough to obviate the need to extend the <tt>PATH</tt>).

{{Note|The following commands should be run from an empty directory<ref name="dedicated-directory-won-t-stay-empty-forever">Well, empty before the first time; later, <tt>download_and_compile.sh</tt> is going to populate it with plenty of FlightGear files and subdirectories, of course.</ref> in a partition that has enough free space (see [[#disk-space-requirements-and-build-time | Disk space requirements and build time]]). As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we are going to choose the directory <tt>~/flightgear/dnc-managed</tt> for this purpose, in order to express that the whole directory tree is managed by <tt>download_and_compile.sh</tt>. This is just an example; feel free to choose another directory if you want.

'''Don't run the commands from a non-dedicated directory,''' because it will be filled with files and directories created by <tt>download_and_compile.sh</tt> and the FlightGear, SimGear, etc. build systems. That would be a complete mess! In particular, ''don't'' run the commands from the directory containing your [[FGMeta]] clone.}}

{{Tip|For some commands, <tt>download_and_compile.sh</tt> may use <tt>sudo</tt>. In case you want to run some other program instead of <tt>sudo</tt>, this can be done with the <code>--sudo</code> option of <tt>download_and_compile.sh</tt>. For instance, in order to see the commands that would be run with sudo without actually running them, you can pass <code><nowiki>--sudo=echo</nowiki></code> to <tt>download_and_compile.sh</tt>. Like all other options, <code>--sudo</code> must be given ''before'' all arguments that are component names (such as <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt>, etc.).}}

The package manager used by <tt>download_and_compile.sh</tt> by default is <tt>apt-get</tt> (it won't be used if you pass <tt>download_and_compile.sh</tt> the <code>-pn</code> option). You can use another one if you wish, as long as it supports the following calls:
''pkg-mgr'' update
''pkg-mgr'' install ''pkg1 pkg2'' ...
This is the case for <tt>aptitude</tt> as well as <tt>apt</tt>. If you want <tt>download_and_compile.sh</tt> to use <tt>aptitude</tt>, give it the option <code><nowiki>--package-manager=aptitude</nowiki></code> before any of the ''COMPONENT'' arguments.

All options of <tt>download_and_compile.sh</tt> can be seen by running the following command:
$ download_and_compile.sh --help

Now the instructions. '''You have chosen a dedicated directory''' where all the stuff that is downloaded and built by <tt>download_and_compile.sh</tt> will be stored. This is <tt>~/flightgear/dnc-managed</tt> if you followed the suggestions given in [[#getting-started-with-download-and-compile-sh-notations|Notations]], and should be empty before you run <tt>download_and_compile.sh</tt> for the first time. However, it is quite correct to start <tt>download_and_compile.sh</tt> from the same directory for subsequent runs, even when non-empty (otherwise, <tt>download_and_compile.sh</tt> would automatically reclone the repositories every time you run it; that would be a sheer waste of time and bandwidth). All that remains to do is to run:
$ mkdir -p ~/flightgear/dnc-managed
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh -s -j$(nproc)
The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

{{Note|Because of the <code>-s</code> option, the above <tt>download_and_compile.sh</tt> command would build the latest stable release of FlightGear. If you want to build the latest Long Term Stable release, use <code>--lts</code> instead. For the previous LTS release, use <code>--old-lts</code>. If you want to build the development version of FlightGear, use none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, but be warned: it may very well be unstable and unsuitable for flying. For more details on these options, see [[#Release selection|Release selection]].}}

When you don't pass any non-option argument to <tt>download_and_compile.sh</tt> as done here, it takes care of the base components needed to run FlightGear in good conditions: <tt>CARES</tt>, <tt>PLIB</tt>, <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> (these are the component names used by <tt>download_and_compile.sh</tt>, i.e., the final arguments one can optionally give in a <tt>download_and_compile.sh</tt> command; in normal speech, they correspond to the {{github source
| proj = c-ares
| repo = c-ares
| text = c-ares
}}, {{sourceforge source
| proj = libplib
| repo = code
| text = PLIB
}}, {{simgear source
| text = SimGear
}}, {{flightgear source
| text = FlightGear
}} and {{fgdata source
| text = FGData
}} repositories, as well as a suitable repository for [[OpenSceneGraph]]). Therefore, the above command is presently exactly equivalent to:
$ download_and_compile.sh -s -j$(nproc) CARES PLIB SIMGEAR FGFS DATA OSG

In case you want to build another component such as, say, CMAKE, you can add it to the command, like this:
$ download_and_compile.sh -s -j$(nproc) CARES PLIB SIMGEAR FGFS DATA OSG CMAKE

When the command terminates, you should have a script called <tt>run_fgfs.sh</tt> in the directory from which you ran <tt>download_and_compile.sh</tt> (i.e., <tt>~/flightgear/dnc-managed</tt> in the suggested setup). This will be your script to run FlightGear. For instance, in order to start the [[FlightGear Qt launcher|built-in launcher]], you can run the following commands:<ref name="no-need-to-change-to-dnc-managed-dir-before-starting-generated-scripts">We give these commands because they are easy to read, but the <code>cd</code> command is not needed if you use the correct path, as in <code>~/flightgear/dnc-managed/run_fgfs.sh --launcher</code>.</ref>
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --launcher
(You may omit the <code>--launcher</code> option; this would simply start FlightGear without any launcher, at the default airport and with the default aircraft.) 
In case you find this tedious to type or have more arguments to pass on a regular basis, you can follow the advice given at the end of [https://sourceforge.net/p/flightgear/mailman/message/36634426/ this message] or use another launcher such as [[FFGo]]—but the [[FlightGear Qt launcher|FlightGear built-in launcher]] started with <code>run_fgfs.sh --launcher</code> is quite fine, be sure to try it first!

{{Note|If you ran <tt>download_and_compile.sh</tt> from <tt>~/flightgear/dnc-managed</tt> as proposed above, the full path of the <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> directory is your [[$FG_ROOT]]. This is a very important path for FlightGear; knowing this may be useful for troubleshooting or doing “advanced things.”}}

=== Updating FlightGear ===

{{Note|If you built FlightGear with either of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, you need to pass the ''same option'' to the <tt>download_and_compile.sh</tt> command given below that will update your FlightGear installation. Otherwise, <tt>download_and_compile.sh</tt> will automatically build the ''next'' suite (bleeding-edge development version), which is probably not what you wish. Moreover, if you do want to switch from one suite to another (for instance from ''stable'' to ''next'', or from ''Long Term Stable'' to ''stable''), using the <code>--cleanup</code> option of <tt>download_and_compile.sh</tt> is heartily recommended.}}

Keeping the above note in mind, go to the directory from which you previously ran <tt>download_and_compile.sh</tt> (<tt>~/flightgear/dnc-managed</tt> in the [[#Notations|suggested setup]]). This is the folder which, if you did a complete run of <tt>download_and_compile.sh</tt> as shown in the previous section, contains the <tt>run_fgfs.sh</tt> script and a log file named <tt>compilation_log.txt</tt> that records what <tt>download_and_compile.sh</tt> did in its last run. If you wish to update, say, {{simgear source
| text = SimGear
}}, {{flightgear source
| text = FlightGear
}}, {{fgdata source
| text = FGData
}} and [[OpenSceneGraph|OSG]], simply execute this:
$ download_and_compile.sh -I -pn -j$(nproc) SIMGEAR FGFS DATA OSG
The <code>-I</code> option tells <tt>download_and_compile.sh</tt> to ignore inter-component dependencies. If you don't use it, other components may be processed too due to these dependencies. The purpose of the behaviour without <code>-I</code> is to help people who aren't necessarily aware of new requirements as time goes (e.g., SIMGEAR and FGFS started to require CARES by the end of 2024; a FlightGear fork of OSG is also required for FGFS ''next'' in 2025). However, it may be frustrating to specify a list of components and see additional ones being automatically added, hence the option.

The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

<tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> are called ''components'' in <tt>download_and_compile.sh</tt> terminology. A component generally corresponds to a software repository, or something close.

Now about the <code>-pn</code>. It is equivalent to <code>-p n</code> and means “don't try to install or update packages from my (Linux) distribution” (<code>y</code> means ''yes, please install or update'', <code>n</code> means ''no, please don't''). In case you forgot that, simply run:
$ download_and_compile.sh --help
What does it imply to pass <code>-pn</code>? This tells <tt>download_and_compile.sh</tt> to completely skip the step where it checks for needed packages from your distribution and installs/updates them, by default using <tt>apt-get</tt>. It thus goes straight to the following steps:
* update each repository corresponding to one of the selected components (<tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> in our example);
* compile each selected component that requires compilation;
* install each selected component in the appropriate place (under <tt>~/flightgear/dnc-managed</tt> according to our [[#getting-started-with-download-and-compile-sh-notations|Notations]]).
In case you don't have all required dependencies for the selected components, one of them is likely to fail, of course, since by passing <code>-pn</code> to <tt>download_and_compile.sh</tt>, you forbid it to install these dependencies for you. So, you can also very well update without passing the <code>-pn</code> option, it will simply take a little longer (the time to check if all dependencies of the selected components are available with <tt>APT</tt>). In fact, this is '''what you should do if the previous <tt>download_and_compile.sh</tt> run failed:''' first update <tt>download_and_compile.sh</tt> (see [[#getting-download-and-compile-sh-using-an-fgmeta-clone|above]]) then run it ''without'' <code>-pn</code><ref name="passing-no-pn-option-equals-passing-py">Which is the same as passing <code>-py</code>.</ref> in case new dependencies have been recently added and you don't have them on your system yet—this would be a very likely cause for the failure. In this case, running <code>download_and_compile.sh --cleanup</code> to restart the build from a clean state is probably a good idea (see [[#Cleaning built and installed files|Cleaning built and installed files]] for details on this option).

'''Summary'''

Routine update:
$ download_and_compile.sh -pn -j$(nproc) ''COMPONENT...''
(add <code>-I</code> if you don't want inter-component dependencies to pull additional components). In case this fails, first update <tt>download_and_compile.sh</tt> (see [[#getting-download-and-compile-sh-using-an-fgmeta-clone|above]]), then run
$ download_and_compile.sh --cleanup
$ download_and_compile.sh -j$(nproc) ''COMPONENT...''
where ''COMPONENT...'' stands for the space-separated list of components you want <tt>download_and_compile.sh</tt> to process.

=== Examining the history of <tt>download_and_compile.sh</tt> ===

Looking at the latest commits that affected <tt>download_and_compile.sh</tt> is quite easy with your FGMeta clone:
$ cd ~/flightgear/fgmeta
$ git log -- download_and_compile.sh
(then quit by typing <tt>q</tt>, assuming your <tt>$GIT_PAGER</tt> is <tt>less</tt>) 

In order to do the same, but also see the patch for each commit:
$ cd ~/flightgear/fgmeta
$ git log -p -- download_and_compile.sh

=== For the curious: the SSH way ===

{{Note|The method described below is not necessary anymore since {{fgmeta commit | 420034d5b51ff2d32fc0c3716b17a2d862841e0f}} (May 2020). Also, it was written at a time where the canonical location for [[FGData]] was at SourceForge; however, in 2025, the canonical location for FGData is {{fgdata source
| text = here
}}.}}

The purpose of this section is to teach you how to clone [[FGData]] using SSH, then change the Git remote setup in your clone of that repository to retrieve further updates using https—which is convenient, as it does not require you to provide a password. This technique used to be necessary to securely retrieve FGData because of a problem in the [https://sourceforge.net/ SourceForge] infrastructure (namely, <code>git clone</code> from SourceForge doesn't work for the big FGData repository using https). This is not needed anymore in 2025.

Because the following method will make you connect to [https://sourceforge.net/ SourceForge] using the SSH protocol, you'll need an account on that site. If you don't already have one, go to the [https://sourceforge.net/user/registration registration page] and create an account. In all this section, we'll assume that your account name at SourceForge is ''SFusername''.

{{Note|As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we assume that your Unix user name (login) is <tt>toto</tt>. Don't confuse the <tt>sudo</tt> password prompt (where you need to enter <tt>toto</tt>'s password) with the password prompt for your SourceForge account! The former appears as
[sudo] password for toto:
whereas the latter is just:
Password:
}}

{{Tip|For some commands, <tt>download_and_compile.sh</tt> may use <tt>sudo</tt>. In case you want to run some other program instead of <tt>sudo</tt>, this can be done with the <code>--sudo</code> option of <tt>download_and_compile.sh</tt>. For instance, in order to see the commands that would be run with sudo without actually running them, you can pass <code><nowiki>--sudo=echo</nowiki></code> to <tt>download_and_compile.sh</tt>. Like all other options, <code>--sudo</code> must be given ''before'' all arguments that are component names (such as <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt>, etc.).}}

{{Note|The commands given below will build the ''next'' suite, which contains the bleeding-edge development version of FlightGear. This is likely to be unstable, possibly unsuitable for flying. If you'd rather build the latest stable release or the latest Long Term Stable release, add option <code>-s</code> or <code>--lts</code> to all <tt>download_and_compile.sh</tt> commands given below (or <code>--old-lts</code> for the previous LTS release). You may add the chosen option right after the <tt>download_and_compile.sh</tt> command name (in any case, the option should come before non-option arguments such as SIMGEAR, FGFS, DATA, etc.). See [[#Release selection|Release selection]] for more explanations on options <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>.}}

Now the instructions. You have chosen a dedicated directory where all the stuff that is downloaded and built by <tt>download_and_compile.sh</tt> will be stored. This is <tt>~/flightgear/dnc-managed</tt> in our example, and should be empty before you run <tt>download_and_compile.sh</tt> for the first time. However, it is quite correct to start <tt>download_and_compile.sh</tt> from the same directory for subsequent runs, even when non-empty (otherwise, <tt>download_and_compile.sh</tt> would automatically reclone the repositories every time you run it; that would be a sheer waste of time and bandwidth).

Ready? Let's go!
<pre>$ mkdir -p ~/flightgear/dnc-managed
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
Fetching DATA with 'git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata'
Cloning into '.'...
The authenticity of host 'git.code.sf.net (216.105.38.16)' can't be established.
ECDSA key fingerprint is SHA256:FeVkoYYBjuQzb5QVAgm3BkmeN5TTgL2qfmqz9tCPRL4.
Are you sure you want to continue connecting (yes/no)?
Warning: Permanently added 'git.code.sf.net,216.105.38.16' (ECDSA) to the list of known hosts.
Connection closed by 216.105.38.16 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
</pre>

The above messages are perfectly normal but deserve a little explanation. Here, <tt>ssh</tt> asked us to confirm that the fingerprint sent by the remote host is that of the real <tt>git.code.sf.net</tt>, as opposed to that of some malicious server ''pretending'' to be <tt>git.code.sf.net</tt>. This confirmation only has to be done once, after which it is remembered thanks to <tt>~/.ssh/known_hosts</tt>. You should visit the [https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/#fingerprint-listing page that gives the host key fingerprint of every publically-accessible SSH server at SourceForge] and carefully check that the fingerprint appearing on your terminal is listed on that page for <tt>git.code.sf.net</tt>, or some matching pattern such as <tt>*.code.sf.net</tt>.

If the fingerprint that is printed on your terminal is not listed on that page, answer <tt>no</tt> to the question ''Are you sure you want to continue connecting (yes/no)?'' and copy/paste to flightgear-devel (see [[Mailing lists]]) the above message from <tt>ssh</tt> that contains the fingerprint sent to you by the remote host which pretends to be <tt>git.code.sf.net</tt>. If this happened, you should stop here and wait for answers from readers of flightgear-devel.

From now on, we'll assume that the fingerprint you received was correct, and therefore that you have answered <tt>yes</tt> to the ''Are you sure you want to continue connecting (yes/no)?'' question.

In this example, it took us several minutes to verify the fingerprint of the <tt>git.code.sf.net</tt> server and confirm it to <tt>ssh</tt>. Because of this delay, <tt>git.code.sf.net</tt> hung up on us and closed the connection. This is absolutely ''not a problem:'' we can just rerun the <tt>download_and_compile.sh</tt> command with the same arguments as the first time. Since we answered <tt>yes</tt> to the ''Are you sure you want to continue connecting (yes/no)?'' prompt, the fingerprint of <tt>git.code.sf.net</tt>'s key has been stored in <tt>~/.ssh/known_hosts</tt>, therefore we won't get this prompt anymore. But if some server claiming to be <tt>git.code.sf.net</tt> presents a host key that has a different fingerprint in the future, <tt>ssh</tt> will print a big fat warning that the server may belong to an attacker trying to impersonate <tt>git.code.sf.net</tt>. Therefore, this SSH host key verification is very useful to protect us from future attacks (which hopefully won't happen at all).

As said, we just rerun the <tt>download_and_compile.sh</tt> command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
Fetching DATA with 'git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata'
Cloning into '.'...
Password:</pre>
As explained above, the preceding prompt is for your SourceForge password (which you could guess from the <code><nowiki>git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata</nowiki></code> command).
<pre>remote: Enumerating objects: 67011, done.
remote: Counting objects: 100% (67011/67011), done.
remote: Compressing objects: 100% (31342/31342), done.
remote: Total 67011 (delta 38776), reused 59640 (delta 33570)
Receiving objects: 100% (67011/67011), 2.60 GiB | 313.00 KiB/s, done.
Resolving deltas: 100% (38776/38776), done.
Checking out files: 100% (12959/12959), done.
Password:</pre>
(It will take a fair amount of time to get there, because this is the complete download of [[FGData]].) 
This is again a prompt for your SourceForge password, because <tt>download_and_compile.sh</tt> wants to run <code>git pull --rebase</code> in the repository (admittedly, it's a bit dumb after a <tt>clone</tt> operation—please forgive us). In case you were not monitoring the <tt>clone</tt> operation, you probably saw the password prompt way after <tt>git.code.sf.net</tt> got bored waiting for you and closed our second connection:
<pre>Connection closed by 216.105.38.16 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.</pre>
(if not, there should be no error message and you should have a clean FGData clone) 
No worries. Just as before, simply rerun the command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
DATA: the repository already exists
Password:
Already up to date.
Current branch next is up to date.
Already on 'next'
Your branch is up to date with 'origin/next'.
All optional package alternatives have found a matching package.

download_and_compile.sh has finished to work.
</pre>
There we are! You now have a clean, up-to-date [[FGData]] clone in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> (remember: <tt>~/flightgear/dnc-managed</tt> is the directory from which you ran <tt>download_and_compile.sh</tt>). Note this place: the full path of the <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> directory is your [[$FG_ROOT]].

Now, change the protocol to use for future updates of your FGData clone:<ref name="changing-the-protocol-for-a-git-remote-manual-method">Another way would be to manually change the relevant line starting with <code>url = <nowiki>ssh://SFusername@</nowiki></code> for the <code>origin</code> remote in the <tt>.git/config</tt> file that lives inside your repository clone (i.e., <tt>~/flightgear/dnc-managed/install/flightgear/fgdata/.git/config</tt> in our example).</ref>
(cd install/flightgear/fgdata && \
git remote set-url origin <nowiki>https://git.code.sf.net/p/flightgear/fgdata</nowiki>)
(you can check at any time the protocol(s) in use with the command <code>git remote -v</code> run inside a Git repository—in this case, inside the folder <tt>install/flightgear/fgdata</tt>). As a consequence of this change, all future updates of your FGData clone will use the <tt>https</tt> protocol, therefore you won't be prompted anymore for your SourceForge password.

All that remains to do is to run, from the same directory as before (<tt>~/flightgear/dnc-managed</tt> in our example):
$ download_and_compile.sh -j$(nproc)
The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

Assuming the compilation was successful, you can now start the [[FlightGear Qt launcher|FlightGear built-in launcher]] using for instance:
$ ./run_fgfs.sh --launcher
See [[#Building FlightGear|Building FlightGear]] for more details.

== List of available components ==

The <tt>download_and_compile.sh</tt> script is able to download, compile (when applicable) and install the following components:

* ATCPIE (for the [[ATC-pie]] air traffic control simulation program)
* CMAKE (for the [https://cmake.org/ CMake] build tool—this can be useful in case CMake is too old in your distribution)
* DATA (for [[FGData]], the main set of data files used by FlightGear)
* FGFS (for FlightGear itself)
* FFGO (for the [[FFGo]] FlightGear launcher)
* FGRUN (for the [[Fgrun|FGRun]] FlightGear launcher)
* FGX (for the [[FGX|FGx]] FlightGear launcher<ref name="note-on-the-status-of-FGx-support-in-download-and-compile-sh">Support for FGx in <tt>download_and_compile.sh</tt> would probably benefit from a code review.</ref>)
* OPENRADAR (for the [[OpenRadar]] air traffic control simulation program)
* OPENRTI (for [[FlightGear HLA support (High Level Architecture)#OpenRTI | OpenRTI]]<ref name="note-on-the-status-of-OpenRTI-support-in-FG">Note that OpenRTI is just an optional dependency for [[FlightGear high-level architecture support | HLA support]]. For the time being, you should be just fine building without it. Eventually, the idea is for HLA to replace the existing MP system and even increasingly distribute the FlightGear architecture such that more and more components can be more easily run in separate threads or even separate processes, possibly even on different machines. So this is going to be an important feature for professional users, using several computers and screens to create a comprehensive and immersive simulation environment.

At the moment, it is probably safe to say that HLA is only of interest to developers and people willing to play with experimental features.</ref>)
* OSG (for the [[OpenSceneGraph]] library)
* PLIB (for the [[PLIB]] library)
* SIMGEAR (for the [[SimGear]] library—foundation for FlightGear and TerraGear)
* TERRAGEAR (for the [[TerraGear]] terrain building toolchain)
* TERRAGEARGUI (for [[TerraGear GUI]], a graphical interface for TerraGear)
* ZLIB (for the [http://www.zlib.net/ zlib] compression library)

Each of the items listed above is a ''component'' in <tt>download_and_compile.sh</tt> terminology. Components are written in uppercase by convention.

{{Note|The preceding list might not be up-to-date. The up-to-date list of components supported by <tt>download_and_compile.sh</tt> can always be obtained by running <code>download_and_compile.sh --help</code>.}}

What is the point of knowing this? Because you may pass component names to <tt>download_and_compile.sh</tt> in order to tell it what you want to download, build and install. By default, only the components [[SimGear|SIMGEAR]], [[FlightGear|FGFS]], [[FGData|DATA]] and [[OpenSceneGraph|OSG]] are taken care of, which means that the command:
$ download_and_compile.sh
is equivalent to:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

In case you'd like to do the same build with just [[PLIB]] added, you could use:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG PLIB

You get the idea. When several components are passed on the same command line, <tt>download_and_compile.sh</tt> chooses a reasonable order for processing, so don't worry about that.

== When building ''next'', you may encounter problems ==

Keeping in mind that this script compiles sometimes bleeding edge software, it can happen that what was successfully compiling last week, does not compile anymore today. Building the latest stable version (option <code>-s</code>) or the latest Long Term Stable release (option <code>--lts</code>) should always work, unless there is a problem with the script (well, in some cases, there may be packages of your distribution that are too recent for <code>--lts</code>; for instance, in July 2020, <code>--lts</code> didn't build with OpenSceneGraph 3.6, but simply passing the OSG component on the <tt>download_and_compile.sh</tt> command solved the problem, because at that time, option <code>--lts</code> selected OpenSceneGraph 3.4).

That said, you may want to build the development version (called ''next''): this is the one developers use all the time, so kindly asking on the flightgear-devel [[Mailing_lists|mailing list]] in case a problem popped up<ref name="what-to-provide-when-asking-for-help">Don't forget in this case to precisely tell what you did and include the <tt>compilation_log.txt</tt> file written by <tt>download_and_compile.sh</tt>.</ref> should allow you to find good advice and get the problem quickly fixed, if it's a new one.

{{Warning|As of July 2020, heavy development will be done on ''next'', the development branch of FlightGear. It is expected to be rather unstable for several months. Unless you are really interested in FlightGear development or in providing feedback to the developers, you're probably better off building either the latest stable version (option <code>-s</code>) or the latest Long Term Stable release (option <code>--lts</code>). In case you want something even older, the previous LTS release can be selected with option <code>--old-lts</code>.}}

== Task-specific instructions ==

{{Note|In this section, we assume you've read and followed the advice given in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]].}}

=== Selecting the components to build ===

By default, <tt>download_and_compile.sh</tt> downloads or updates, then compiles, [[SimGear]], FlightGear, [[FGData]] and [[OpenSceneGraph|OSG]] (more precisely, FGData is downloaded but not compiled—that wouldn't make sense). This is what happens when running:
$ download_and_compile.sh
The preceding command is therefore equivalent to:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

To make <tt>download_and_compile.sh</tt> take care of other programs or libraries, use non-option arguments naming the ''components'' you want, for instance:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG CMAKE
SIMGEAR, FGFS, DATA, OSG and CMAKE are the component names respectively corresponding to [[SimGear]], FlightGear, [[FGData]], [[OpenSceneGraph]] and [https://cmake.org/ CMake] in <tt>download_and_compile.sh</tt>'s terminology.

A [[#list-of-available-components|list of available components]] is provided on this page, but the fully up-to-date list can always be obtained by running <code>download_and_compile.sh --help</code>.

=== Choosing between stable and development versions ===

By default, <tt>download_and_compile.sh</tt> fetches code and data from development branches of the source repositories (which sometimes causes compilation or runtime errors). However, it is possible to tell the script to download the latest “stable” version of each component, for some suitable definition of “stable”. This is by means of the <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> options:
$ download_and_compile.sh -s ''COMPONENT1 COMPONENT2...''
or
$ download_and_compile.sh --lts ''COMPONENT1 COMPONENT2...''
or
$ download_and_compile.sh --old-lts ''COMPONENT1 COMPONENT2...''

How does it work?
* For [[SimGear]], FlightGear and [[FGData]], <code>-s</code> uses the most recent stable release branch of the corresponding Git repository, <code>--lts</code> uses the most recent Long Term Stable release (LTS) and <code>--old-lts</code> uses the previous LTS release.
* For other components, a known-stable version is selected by <tt>download_and_compile.sh</tt>, which may be influenced by the use of <code>-s</code>, <code>--lts</code> or <code>--old-lts</code>.

So, as far as the SIMGEAR, FGFS and DATA components are concerned, you can:
* build the latest stable release (<code>-s</code>);
* build the latest Long Term Stable release (<code>--lts</code>);
* build the previous Long Term Stable release (<code>--old-lts</code>);
* build the current development version (bleeding edge), which lives in the {{flightgear source
| branch = next
| text = next
}} branch of the FlightGear repository.
The use of <code>-s</code>, <code>--lts</code> or <code>--old-lts</code> also influences the version of other components you may have selected (this can be overridden using <code>--component-branch</code> for advanced users—see [[#Component-specific settings|Component-specific settings]]).

{{Note|In a given folder where <tt>download_and_compile.sh</tt> is run, you should normally either always use the <code>-s</code> option, or always use <code>--lts</code>, or always use <code>--old-lts</code>, or always none of these (in other words, stick to the same suite: latest stable, latest LTS, previous LTS or ''next'', consistently accross all components).}}

Actually, it ''is'' possible to switch between suites but you have to use the <code>--cleanup</code> option when doing the switch (see [[#Cleaning built and installed files|Cleaning built and installed files]] for information on this option). For instance:
* Build with <code>-s</code> as many times as you want.
* Want to try ''next''? Okay, then build once with <code>--cleanup</code> (no <code>-s</code> option anymore).
* You can then perform as many builds of ''next'' as you want; no need to use <code>--cleanup</code> unless something special went wrong.
* If you later decide to switch back to the stable release, build once with <code>-s</code> and <code>--cleanup</code>, then only with <code>-s</code> for further builds.
* etc.

This way, ''you don't need to download the repositories again'' when trying the various suites. In particular, you can switch between ''next'', stable, LTS and old LTS without downloading nor having several copies of [[FGData]] on your hard drive. (This works because a Git repository may internally contain data for several branches, even if only one is “normally visible” in the filesystem at a given time.)

==== Building the latest Long Term Stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>--lts</code> option to build the latest Long Term Stable release:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --lts
(In this example, the implicitly-selected components are SIMGEAR, FGFS and DATA, as explained [[#selecting-the-components-to-work-on | above]].)

{{Note|If you decide to use the <code>--lts</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>--lts</code> option for some components and not for others is not supported.}}

==== Building the latest stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>-s</code> option to build the latest stable release:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh -s

{{Note|If you decide to use the <code>-s</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>-s</code> option for some components and not for others is not supported.}}

==== Building the current FlightGear development version ====

When executing <tt>download_and_compile.sh</tt> without any option, the development version of every selected component is built:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh

{{Note|The development version of FlightGear changes on an almost daily basis. It provides the latest features, but is not guaranteed to always work reliably. If you don't want to take the risk of finding new bugs when updating, you may prefer to use the latest stable release.}}

==== Building the previous Long Term Stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>--old-lts</code> option to build the previous Long Term Stable release (i.e., oldish code):
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --old-lts
(In this example, the implicitly-selected components are SIMGEAR, FGFS and DATA, as explained [[#selecting-the-components-to-work-on | above]].)

{{Note|If you decide to use the <code>--old-lts</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>--old-lts</code> option for some components and not for others is not supported.}}

=== Overriding the source repository or branch for a component ===

This section shows how to override the location and/or branch from which a given component will be downloaded.

{{Warning|The rest of this section is for people who know what they are doing. Don't use the following unless you trust the person who publishes the repository and have good reasons to believe that it has been kept up-to-date.}}

==== A short example ====

Let's start with an example to make it easier to understand to following paragraphs. Suppose we want to build the current stable release of FlightGear, linked against an [[OpenSceneGraph]] library whose source code is to be retrieved from branch <tt>fgfs-osg-36-2</tt> of the Git repository located at [https://gitlab.com/flightgear/openscenegraph.git https://gitlab.com/flightgear/openscenegraph.git] (this is actually the default in September 2024). Since the default protocol used when <tt>download_and_compile.sh</tt> clones a repository is [https://en.wikipedia.org/wiki/HTTPS HTTPS], this can be done with
download_and_compile.sh --cleanup -s \
--override-repo OSG=GitLab:gitlab.com/flightgear/openscenegraph.git \
--component-branch OSG=fgfs-osg-36-2 SIMGEAR FGFS DATA OSG

==== The site name ====

<tt>download_and_compile.sh</tt> uses case-insensitive short names such as <tt>GitLab</tt>, <tt>GitHub</tt>, <tt>SourceForge</tt> and <tt>gitlab.kitware.com</tt> as keys in order to identify the settings describing where and how a given component will be initially fetched (these settings are effective at clone time; later updates simply use the settings recorded in the local repository). These names are referred to as ''site'' in the output of <code>download_and_compile.sh --help</code>, in particular in the <tt>--git-clone-site-params</tt> and <tt>--override-repo</tt> options we'll present below. These ''site'' keys are simply identifier strings; they are not used in the DNS queries.

==== The protocol ====

Current <tt>download_and_compile.sh</tt> (from December 2022) fetches the source code of most components from Git repositories (earlier versions used Subversion for some components); a few non-core components (currently [[FGo!]] and [[OpenRadar]]) are fetched using <tt>wget</tt> and are out-of-scope for this section.

The default protocol used by <tt>download_and_compile.sh</tt> when cloning a Git repository is [https://en.wikipedia.org/wiki/HTTPS HTTPS]. This can be overridden using the <tt>--git-clone-default-proto</tt> option. In other words, the default is <tt>--git-clone-default-proto=https</tt> (the protocol name is case-insensitive). Other possibilities for the protocol are <tt>git</tt> and <tt>ssh</tt>.

{{Warning|The <tt>git</tt> protocol doesn't protect against man-in-the-middle attacks; use at your own risk! Unfortunately, “clever” people often recommend it on the forum without mentioning its downsides.}}

Using the <tt>ssh</tt> protocol as the argument of <tt>--git-clone-default-proto</tt> has little use, because in general you'll want to specify a particular username when using SSH and this username is likely not to be the same for all components you intend to clone via SSH (right, <tt>~/.ssh/config</tt> can be used to automatically provide a site-dependent username). That is why <tt>download_and_compile.sh</tt> offers the <tt>--git-clone-site-params</tt> option.

==== Site-specific settings ====

Using
--git-clone-site-params ''SITE''=''PROTOCOL''[:''USERNAME'']
you can tell <tt>download_and_compile.sh</tt> that every component fetched from ''SITE'' should be cloned with the specified protocol and username (allowed protocols are <tt>https</tt>, <tt>ssh</tt> and <tt>git</tt>).

{{Note|In case you have several repositories at a given site (say, GitHub) and need to use different SSH usernames for these repositories, you can use different site names:
<pre>
--override-repo COMPONENT_A=GitHubA:ADDRESS_A
--git-clone-site-params GitHubA=ssh:userA
--override-repo COMPONENT_B=GitHubB:ADDRESS_B
--git-clone-site-params GitHubB=ssh:userB</pre>
Here, the site names are <tt>GitHubA</tt> and <tt>GitHubB</tt>; the <tt>--override-repo</tt> option will be presented below.

By default, <tt>download_and_compile.sh</tt> case-insensitively uses the <tt>GitLab</tt> (resp. <tt>SourceForge</tt>) site name to identify the settings used when cloning a repository from gitlab.com (resp. git.code.sf.net). Therefore, the settings for GitHubA and GitHubB in this example would only apply to components ''c'' for which --override-repo ''c''<nowiki>=</nowiki>GitHubA:... or --override-repo ''c''<nowiki>=</nowiki>GitHubB:... has been specified.}}

==== Component-specific settings ====

The <tt>--override-repo</tt> and <tt>--component-branch</tt> options allow one to override the default settings used by <tt>download_and_compile.sh</tt> for cloning the repository corresponding to the specified component (they only apply to components whose source code is retrieved with Git). The syntax of these options is
--override-repo ''COMPONENT''=''SITE'':''ADDRESS''
and
--component-branch ''COMPONENT''=''BRANCH''
In this syntax:
* ''COMPONENT'' represents the name of a component for <tt>download_and_compile.sh</tt> (e.g., <tt>SIMGEAR</tt>—see [[#List of available components|List of available components]]);
* ''ADDRESS'' is something like <tt>gitlab.com/flightgear/simgear.git</tt> (don't include any <tt>protocol://</tt> part in ''ADDRESS'');
* ''BRANCH'' should be the name of an existing branch of the Git repository hosted at ''ADDRESS'';
* ''SITE'' is a string used as a key in a mapping; <tt>download_and_compile.sh</tt> uses it to find out how to connect to ''ADDRESS'' in order to clone the repository for ''COMPONENT'' (see [[#Site-specific settings|Site-specific settings]]).
See the [[#A short example|above example]] for a concrete example where these options are used.

{{Note|The argument of any long option of <tt>download_and_compile.sh</tt> that takes an argument may be introduced immediately after the option name using an equal sign. However, in the above cases, I find this way a bit confusing because the option value ''also'' uses an equal sign as separator. Hence the above use of separate command arguments: one for the option name, one for its argument.}}

=== Passing custom arguments to CMake ===

Sometimes, when building a program, you may want to enable a feature that is not enabled by default, or disable a feature that is enabled by default. With recent versions of <tt>download_and_compile.sh</tt> (October 2020 or later), this can be done for SimGear and FlightGear using the <code>--sg-cmake-arg</code> and <code>--fg-cmake-arg</code> options (the environment variables <tt>SG_CMAKEARGS</tt> and <tt>FG_CMAKEARGS</tt> are still supported, but they don't allow one to pass arguments containing spaces). For instance, in order to link SimGear with the system Expat library, you can do:
$ download_and_compile.sh --sg-cmake-arg='-DSYSTEM_EXPAT=ON' SIMGEAR
Similarly, disabling HID-based input when building FlightGear can be achieved this way:
$ download_and_compile.sh --fg-cmake-arg='-DENABLE_HID_INPUT=OFF' FGFS

{{Note|Such options are typically defined in <tt>CMakeLists.txt</tt> files, for example {{simgear source
| path = CMakeLists.txt
| text = here
}} for SimGear and {{flightgear source
| path = CMakeLists.txt
| text = here
}} for FlightGear.}}

This can be useful, for instance, to work around bugs in a part of SimGear or FlightGear that you don't need, but causes a build or runtime failure (see {{forum link|t=35740|text=here}} for example). This is often convenient when using the development version of FlightGear, but doesn't mean such bugs shouldn't be reported!

If you have several such options to pass, just use <code>--sg-cmake-arg</code> and/or <code>--fg-cmake-arg</code> several times:
$ download_and_compile.sh --fg-cmake-arg='-DENABLE_SWIFT=ON' \
--fg-cmake-arg='-DENABLE_HID_INPUT=OFF' FGFS
It is even possible to pass arguments containing spaces to CMake, as in:
$ download_and_compile.sh \
--sg-cmake-arg='-DCMAKE_CXX_FLAGS=-Wno-deprecated-declarations -Wall' \
SIMGEAR
(just a silly example to show a working syntax) or:
$ download_and_compile.sh \
--fg-cmake-arg="-DCMAKE_CXX_FLAGS=$(pkg-config --cflags gl)" \
FGFS
Note the use of double-quotes here to enable the <code>$(...)</code> command substitution.

Using the (half-deprecated) environment variables <tt>SG_CMAKEARGS</tt> and <tt>FG_CMAKEARGS</tt>, it is also possible to define CMake arguments in a single place that are going to be used for both SimGear and FlightGear. However, this technique doesn't allow one to pass arguments containing spaces to CMake.
$ export SG_CMAKEARGS='-DSYSTEM_EXPAT=ON'
$ export FG_CMAKEARGS='-DENABLE_SWIFT=ON -DENABLE_HID_INPUT=OFF'
$ download_and_compile.sh

=== Seeing the compilation commands run by Make ===

As a simple application of the previous section, the following options are often useful. When passed to <tt>download_and_compile.sh</tt>, these options cause the compilation commands run via Make to be printed on the terminal and recorded in the compilation_log.txt file:
--sg-cmake-arg='-DCMAKE_VERBOSE_MAKEFILE=1' \
--fg-cmake-arg='-DCMAKE_VERBOSE_MAKEFILE=1'
(the backslash is unneeded if you put both options on the same line). Passing the value 0 instead of 1 would explicitly request the default, non-verbose behavior.

=== Launching FlightGear ===

When using <tt>download_and_compile.sh</tt>, apart from those installed with the package manager, the FlightGear dependencies (which are typically libraries) are not installed system-wide but under the directory from which <tt>download_and_compile.sh</tt> was run. This makes it possible to easily use, for instance, different [[OpenSceneGraph]], [[SimGear]] and FlightGear versions on a single system—e.g., for testing purposes—but also to have separate build trees (optimized/debug). This is also why you either need to set LD_LIBRARY_PATH to run the built programs, or simply use the scripts created by <tt>download_and_compile.sh</tt> in the directory where it is run, such as <tt>run_fgfs.sh</tt> and <tt>run_fgfs_debug.sh</tt>: these scripts automatically set up the required environment variables according to your build settings before firing the desired program (e.g., <tt>fgfs</tt>) with the arguments you provided.

Therefore, the simplest way to run a FlightGear program built by <tt>download_and_compile.sh</tt> is to launch the <tt>run_fgfs.sh</tt> script that <tt>download_and_compile.sh</tt> created in the directory from which it was run, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --launcher

{{Note|<code>./run_fgfs.sh --launcher</code> starts FlightGear with its built-in launcher. If you just do <code>./run_fgfs.sh</code>, FlightGear will be started without any launcher, at the default airport and with the default aircraft.}}

In order to start FlightGear without any launcher, at a given airport (say, [https://en.wikipedia.org/wiki/Paro_Airport Paro airport], whose ICAO code is VQPR) and with a chosen aircraft, you can do:
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --airport=VQPR --aircraft=dhc6
Actually, the directory change is not needed, we only gave it here for readability. Therefore, the following single command does the same:
$ ~/flightgear/dnc-managed/run_fgfs.sh --airport=VQPR --aircraft=dhc6

=== Avoiding multiple downloads of FGData ===

Some people use <tt>download_and_compile.sh</tt> to maintain several directory trees such as the tree starting at <tt>~/flightgear/dnc-managed</tt> in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]] (this can be useful if you want to have one tree with programs compiled in Release mode and another tree where they are built in Debug mode, for instance). This can easily be done by running <tt>download_and_compile.sh</tt> in each of the directories. But since [[FGData]] is so large, it may be tempting to share a single instance of this repository among several trees. This is not officially supported, but apparently can be made to work with symbolic links.

Let's show how this can be done on an example. Suppose your master copy of FGData is in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt>. Then the following appears to work:
$ mkdir -p ~/flightgear/other-dnc-managed-tree/install/flightgear
$ cd ~/flightgear/other-dnc-managed-tree/install/flightgear
$ ln -s ../../../dnc-managed/install/flightgear/fgdata
$ cd ~/flightgear/other-dnc-managed-tree
$ download_and_compile.sh

The last of these commands will use and update the FGData repository present in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt>.

{{Warning|This can only work simply if all trees that share a given FGData repository are from the same release (e.g., current stable or development). Running a “stable“ FlightGear with FGData from the ''next'' branch or the other way round, a development version of FlightGear with FGData from a release branch, doesn't work—and FlightGear should tell you when you start it in such a situation.

That said, people comfortable with Git can check out the correct FGData branch before building or starting FlightGear, for instance:
$ cd /path/to/fgdata && git checkout release/2019.1
or
$ cd /path/to/fgdata && git checkout next
So, this is possible but somewhat acrobatic. You've been warned.}}

Note: there is a [[Avoiding multiple downloads of FGData on Linux|wiki article about this subject]], but it is severely outdated as of April 2019.

== Additional programs ==

{{Note|In this section, we assume you've read and followed the advice given in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]].}}

If you wish to get other programs (precisely: download, build and install them), you need to launch <tt>download_and_compile.sh</tt> with the desired component names as arguments. For instance:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

See [[#list-of-available-components|above]] for the list of available components.

=== TerraGear ===

Run <tt>download_and_compile.sh</tt> with the TERRAGEAR component in order to build and install the [[TerraGear]] terrain building toolchain:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh TERRAGEAR

This creates the following scripts in <tt>~/flightgear/dnc-managed</tt>:
* <tt>run_genapts850.sh</tt>
* <tt>run_ogr-decode.sh</tt>
* <tt>run_tg-construct.sh</tt>
These scripts themselves run the corresponding TerraGear tools, as expected.

=== TerraGear GUI ===

[[TerraGear GUI]] is a graphical interface for [[TerraGear]] written with the Qt toolkit (still Qt 4 in 2019, but it works). In order to install it, run <tt>download_and_compile.sh</tt> with the TERRAGEARGUI component:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh TERRAGEARGUI
This will create a <tt>run_terrageargui.sh</tt> script in <tt>~/flightgear/dnc-managed</tt>, and also a default configuration file <tt>~/.config/TerraGear/TerraGearGUI.conf</tt>, unless you already have one. This default configuration file contains paths to the TerraGear and [[$FG_ROOT]] directories, assuming you have installed the TERRAGEAR and DATA components.

To run TerraGear GUI:
$ cd ~/flightgear/dnc-managed
$ ./run_terrageargui.sh

=== FGCom ===

{{Note|[[FGCom]] has been integrated into FlightGear long ago, therefore the following is not needed in general.}}

[[FGCom]] is the system used by FlightGear to simulate radio communications between users. It is automatically built and installed when you tell <tt>download_and_compile.sh</tt> to take care of the FGFS component. You can launch the standalone FGCom program by using the <tt>run_fgcom.sh</tt> script:
$ cd ~/flightgear/dnc-managed
$ ./run_fgcom.sh

=== FGRun ===

{{Note|As of 2019, FGRun has been superseded by the [[FlightGear Qt launcher|FlightGear built-in launcher]]. The built-in launcher is the most actively maintained launcher for FlightGear. Other launchers are [[FFGo]] and [[FGX|FGx]].}}

[[File:fgrun-page2.jpg|thumb|right]]
Before FlightGear had its built-in launcher (the one you get with <code>run_fgfs.sh --launcher</code>), many users found comfortable having FlightGear launched by the graphical utility [[Fgrun|FGRun]]. This program is built and installed when <tt>download_and_compile.sh</tt> is run with the FGRUN component. You then have to launch the <tt>run_fgrun.sh</tt> command, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgrun.sh

FGRun will save its settings in <tt>~/.fltk/flightgear.org/fgrun.prefs</tt>. You may want to save copies of the preferences customized for stable and next.

=== FGo! ===

{{Note|As of 2019, FGo! is not maintained anymore. You may want to try the built-in launcher (started with <code>run_fgfs.sh --launcher</code>) or [[FFGo]].}}

[[File:Fgo01.jpg|thumb|left]]
FGo! is a graphical utility written in [[python]]. It is downloaded and installed when <tt>download_and_compile.sh</tt> is run with the FGO component. You then have to launch the <tt>run_fgo.sh</tt> command, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgo.sh

Remember that the first time you run it, you have to go to open the ''Preferences'' dialog and set the paths to the <tt>fgfs</tt> executable and to FGData.

== Troubleshooting ==

=== Compilation errors ===
Here we are, no fear, if you wish to use programs from the cvs/svn/git repositories, you might face compilation errors that will prevent you to have a working copy of one or more of the programs provided by this script. What can be the causes that prevent us from successfully compiling? As far as I know those:
# Software developers introduce a new functionality with a new piece of code that prevents the compilation under your architecture, this can happen working with cvs/svn/git sources.
# The program refuses to compile because of a divergence in the libraries on which it depends. For example FlightGear might not compile because OSG has been modified, while OSG itself compiles fine, FG won't.
# One or more repositories are down and you can't get the library you need. (Both from cvs/svn/git or apt-get)

There is a simple solution to the above errors: wait and relaunch the script after some time (hours or days), if software developers repair or synchronize their code with the newly updated libraries (which generally happens eventually), your FlightGear will compile fine as if the previous error never took place.

Sometimes it happens that the script fails to compile only [[Fgrun|FGRun]], [[FGCom]] or atlas, if you then see the run_fgfs.sh file it means that FlightGear installation was successful and you can safely run it.

=== OpenRTI undefined reference errors ===

Sometimes, due to the way <tt>download_and_compile.sh</tt> builds projects, linking errors might occur. This is the case with the error “libRTI-NG.so: undefined reference to xxx”. You might want to patch the <tt>download_and_compile.sh</tt> script to clean OpenRTI with <code>rm -f CMakeCache.txt && rm -rf CMakeFiles/</code>, or just restart the build in a clean environment. Assuming you are in the base directory from which you ran <tt>download_and_compile.sh</tt>, you can run <code>download_and_compile.sh --cleanup</code> (see [[#Cleaning built and installed files|Cleaning built and installed files]]). Alternatively, the following command could be used:
$ rm -rf build/* install/simgear/ install/openrti/ install/flightgear/share/ install/flightgear/bin/

See {{forum link|t=26244|text=this thread}} for more details. Note that <tt>download_and_compile.sh</tt> didn't have the <code>--cleanup</code> option at that time!

== Options ==

=== Release selection ===

* Build the latest stable release: <code>-s</code>
* Build the latest Long Term Stable release: <code>--lts</code>
* Build the previous Long Term Stable release: <code>--old-lts</code>

Long Term Stable (<code>--lts</code>) is supposed to yield a more stable setup than what you would obtain with option <code>-s</code>, however it will generally be older. Both of these options are suitable for users.

If you pass none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> in a <tt>download_and_compile.sh</tt> invocation, you'll build the the ''next'' suite, which contains the development version of FlightGear. The corresponding FlightGear code will be very recent but may well be unstable—this is particularly the case starting from July 2020. This is therefore mostly intended for developers.

=== Skipping most prompts ===

For some important things, <tt>download_and_compile.sh</tt> asks for confirmation in order to be sure that you are well informed about what will be done. When you have a good understanding of these informations, you may want to use the <code>--non-interactive</code> option in order to suppress these prompts (technically, this causes the default answer to be automatically used).

=== Cleaning built and installed files ===

Option <code>--cleanup</code> causes <tt>download_and_compile.sh</tt> to remove everything that was built and installed in the directory it is run from. The Git repositories will not be removed, so this is good if you want to restart a compilation from a clean state.

If you use <code>--cleanup</code> without specifying any component, only this removal will be done (nothing will be compiled nor installed). Otherwise, the usual rules concerning components apply.

=== Multicore acceleration ===

Passing option <code>-j x</code> to <tt>download_and_compile.sh</tt> (where ''x'' is the number of your CPU cores you wish to assign to the job) will considerably speed up the compilation steps. Passing <code>-j$(nproc)</code> is a convenient way to automatically use all available cores.

=== Advanced options ===

* Build a release version: <code>-b Release</code>
* Build a version that should run as fast as a release build, yet has debug information that can be used to post backtraces: <code>-b RelWithDebInfo</code> (this is the default)
* Build a full debug version for very complete bug reporting: <code>-b Debug</code>
* Skip download of distro packages (i.e., by default: <tt>apt-get install ...</tt>): <code>-p n</code>
* Skip retrieving of component downloads and updates (which typically use Git or wget): <code>-d n</code>
* Skip the configure step (like running [https://cmake.org/ CMake] or [https://www.gnu.org/software/autoconf/ autoconf]'s <tt>./configure</tt>): <code>-r n</code>
* Skip compilation of programs: <code>-c n</code>
* Build with compositor: <code>--compositor</code>
* Force the use of a particular branch for a given component: <code>--component-branch ''COMPONENT=BRANCH''</code> (e.g., <code>--component-branch OSG=OpenSceneGraph-3.6</code>, <code>--component-branch FGFS=next</code>, etc.—but remember that components FGFS, SIMGEAR and DATA must ''always'' be in sync). See [[#Component-specific settings|Component-specific settings]] for details.
* Override the repository from which a given component is initially fetched: <code>--override-repo ''COMPONENT''=''SITE'':''ADDRESS''</code> (see [[#Component-specific settings|Component-specific settings]]).
* Generate build.ninja files and build using Ninja: <code>-G Ninja</code>
* Run CMake in verbose mode: <code>--verbose</code> (this shows compilation commands)

For example, if you are a developer and wish to quickly recompile and reinstall only your own modifications for FlightGear, you can do this:
$ download_and_compile.sh -j$(nproc) -p n -d n -r n FGFS

Note that this is the same as:
$ download_and_compile.sh -j$(nproc) -pn -dn -rn FGFS

This command will only rebuild modified files and reinstall FlightGear. Note that depending on the kind of changes you made, reconfiguring and thus dropping the <code>-rn</code> option may be necessary, though (this is the case in particular if you added or removed C++ files).

=== ccache ===
[https://ccache.dev/ ccache] is a compiler cache that enormously speeds up subsequent recompilations (compilation times are often divided by a factor 6 or more). SimGear and FlightGear 2024.1 or later perform <tt>ccache</tt>-enabled builds when <code>-DENABLE_CCACHE=ON</code> is passed to [https://cmake.org/ CMake]. For <tt>download_and_compile.sh</tt> users, there are several ways to do this.

The simplest way is to pass <code>--enable-ccache</code> to <tt>download_and_compile.sh</tt>. This has an effect when processing components such as <tt>SIMGEAR</tt> and <tt>FGFS</tt>; other components may support the option or ignore it. Using this option is equivalent to passing <code>--cmake-arg ALL="-DENABLE_CCACHE=ON"</code> to <tt>download_and_compile.sh</tt>. This causes the script to pass <code>-DENABLE_CCACHE=ON</code> to all CMake-based components that are processed. For those that don't support this option, you'll see a harmless warning that you can safely ignore:

<pre>
CMake Warning:
Manually-specified variables were not used by the project:

ENABLE_CCACHE
</pre>

Finally, if you prefer, you can pass <code>-DENABLE_CCACHE=ON</code> to specific components using for instance
--cmake-arg SIMGEAR="-DENABLE_CCACHE=ON"
and/or
--cmake-arg FGFS="-DENABLE_CCACHE=ON"
This results in longer command lines than the previous methods but allows one to avoid the warning, if it bothers you.

{{Note|<tt>download_and_compile.sh</tt> automatically installs <tt>ccache</tt> if its seems required and package installation hasn't been disabled. Otherwise, you can install it yourself using <code>apt install ccache</code> before using <code>--enable-ccache</code> or similar.}}

== Optimus technology ==
If your computer has a GPU with Optimus technology, you need a dedicated script in order to make FlightGear run with the powerful GPU.

After having installed required tools (Bumblebee) you just need to run this command line in your FlightGear installation directory (where you executed <tt>download_and_compile.sh</tt>):
$ sed 's|\./fgfs|optirun ./fgfs|' run_fgfs.sh > run_fgfs_optirun.sh && chmod +x run_fgfs_optirun.sh
Now you can run FlightGear with <code>./run_fgfs_optirun.sh</code>.

The same can be done for the [[FlightGear_Launch_Control|FGRun]] launcher:
$ sed 's|\./fgrun|optirun ./fgrun|' run_fgrun.sh > run_fgrun_optirun.sh && chmod +x run_fgrun_optirun.sh

== See also ==

* {{fgmeta source
| path = fg-from-scratch
| text = fg-from-scratch
}};
* [[Fedora Packages and Compiling]];
* [[Superbuild]];
* [http://geoffmclane.com/fg/fgfs-052.htm Another script] for building FlightGear and all its dependencies in an automated fashion. The page seems a bit oldish, though (as of 2019).

== References ==
<references/>

[[Category:Building from source]]

[[fr:Script de compilation sous Linux Debian/Ubuntu]]
[[nl:Compileren met een Script op Linux Debian/Ubuntu]]

Hangar catalog

2026-04-12T09:35:01Z

Rominet: Refresh contents: fg-build-catalog, new locations for official catalog.xml files, etc.

{{Package Management}}
The default '''hangar catalog''', <code>catalog.xml</code>, is used by the [[FlightGear Qt launcher | FlightGear built-in launcher]] to list all aircraft of the [[FGAddon|official FGAddon FlightGear hangar]]. [[Flightgear hangars#Third party sites|3rd party hangars]] can also provide a catalog URL via their own <code>catalog.xml</code> file.

== Catalog generation ==
The <code>catalog.xml</code> file can be generated using <tt>fg-build-catalog</tt> from the [https://pypi.org/project/FlightGear/ <code>flightgear</code> Python package] built from {{fgmeta-python source | text=fgmeta-python}} (the script was previously called <tt>update-catalog.py</tt> and was located in [[FGMeta]]). Configuration files and templates for <tt>fg-build-catalog</tt> that are used to generate the catalog for the [[FGAddon]] official hangar are contained in the {{fgmeta-python source | path = catalog | text = catalog}} directory. To generate the FGAddon catalog, as an example, you need to install the <code>flightgear</code> Python package according to the instructions in {{fgmeta-python source
| path = README.md
| text = fgmeta-python's README.md file
}}, then run a command like:

<syntaxhighlight lang="sh">
fg-build-catalog --no-update fgaddon-trunk-catalog
</syntaxhighlight>

You'll likely want to run this ''from a directory where you've copied and adjusted the configuration files.'' Output files will be written to the current directory by default, in particular to the <tt>output</tt> subdirectory. See {{fgmeta-python source
| path = catalog/README.md
| text = catalog/README.md
}} for more detailed instructions.

The idea is to create a subdirectory tree for each catalog (<tt>fgaddon-trunk-catalog</tt> in the above example). This subdirectory can have any name; it contains the configuration and administrative files for maintaining the catalog. The <tt>catalog.config.xml</tt> config file inside the catalog directory will need to be adjusted for each new hangar. The script builds the contents locally which then needs to be uploaded to an appropriate place on a server (<tt>fg-build-catalog</tt> can perform the upload itself: see the {{fgmeta-python source
| path = catalog/fgaddon-trunk-catalog/catalog.config.xml
| text = FGAddon trunk catalog configuration
}} for instance).

== See also ==
=== Wiki articles ===
* [[Aircraft Center]]
* [[Catalog metadata]]
* [[FlightGear hangars#Third party sites]] - List of third-party hangars, of which some have a <code>catalog.xml</code> file.

=== Mailing list threads ===
* [https://sourceforge.net/p/flightgear/mailman/message/35488166/ <nowiki>[</nowiki>Flightgear-devel<nowiki>]</nowiki> Testing changes to update_catalog.py] (November 2016)

=== Source code ===
* {{fgmeta-python source | path = src/flightgear/meta/scripts/catalog/fg_build_catalog.py | text = Main source file for fg-build-catalog}}
* {{fgmeta-python source | path = catalog | text = Official catalog configuration and templates}}

=== Default catalog ===
* Default location of the [http://mirrors.ibiblio.org/flightgear/ftp/Aircraft-trunk/catalog.xml FGAddon trunk catalog.xml file]
* Default location of the [http://mirrors.ibiblio.org/flightgear/ftp/Aircraft-2024/catalog.xml FGAddon 2024.1.* catalog.xml file]

[[Category:Aircraft enhancement]]
[[Category:FlightGear]]

Howto:Model with parameters

2026-03-19T19:28:13Z

Rominet: Typo

Using '''parameters in modeling''' makes it possible for example, to [[Howto: Animate models|animate]] each single propeller of an multi-engined [[aircraft]] without the need to copy the engine model. This reduces the overall filesize and makes it easier for the developer to update the engine animations (just one file to edit).

== Examples ==
The parameters are set in the same file that is used to position the models. In the example below we have two engines.

<syntaxhighlight lang="xml">
<model>
<path>Aircraft/747-400/Models/Engines/GE_CF6-80C2B1F.xml</path>
<overlay>
<params>
<n1>/engines/engine[0]/n1</n1>
</params>
</overlay>
</model>

<model>
<path>Aircraft/747-400/Models/Engines/GE_CF6-80C2B1F.xml</path>
<overlay>
<params>
<n1>/engines/engine[1]/n1</n1>
</params>
</overlay>
</model>
</syntaxhighlight>

In the model's .xml file (<tt>GE_CF6-80C2B1F.xml</tt> in the example above), we place the following parameter declaration and [[Howto: Animate models|animation]]:

<syntaxhighlight lang="xml">
<params>
<n1>/engines/engine[0]/n1</n1>
</params>

<animation>
<type>spin</type>
<object-name>Blades</object-name>
<property alias="../../params/n1"/>
<center>
<x-m>0</x-m>
<y-m>0</y-m>
<z-m>0</z-m>
</center>
<axis>
<x>-1.0</x>
<y>0</y>
<z>0</z>
</axis>
</animation>
</syntaxhighlight>

This spins the "Blades" object with the speed (rpm) of the n1 properties, as defined in the parameters .xml file. For one engine this is <tt>/engines/engine[0]/n1</tt>, for the other <tt>/engines/engine[1]/n1</tt>. The parameters declaration at the top of the code is not required, but it is good for parameter-documentation and gives a default value.

Practically anything can be "aliased," not just <tt><property></tt> tags in animations. Some other examples:

<syntaxhighlight lang="xml">
<animation>
<type>select</type>
<object-name>BladesBlur</object-name>
<condition>
<greater-than>
<property alias="../../../../params/n1" />
<value>20</value>
</greater-than>
</condition>
</animation>
</syntaxhighlight>

This selects the "BladesBlur" object if the n1 property is above 20. Notice that the number of "<tt>../</tt>"s in the <tt>alias</tt> attribute is different. This is because "<tt>../</tt>" actually navigates "up" in the XML tree, much like one would type <tt>cd ..</tt> in a command line to navigate "up" in a file directory tree. Since the aliased tag is further down in the tree, at /propertylist/animation/condition/greater-than/property, we need to add more "<tt>../</tt>"s in the beginning to get back to the root.

Other examples:

<syntaxhighlight lang="xml">
<animation>
<type>material</type>
<object-name>InstrumentFrames</object-name>
<emission>
<red>0.5</red>
<green>0.5</green>
<blue>0.5</blue>
<factor-prop alias="../../../params/light-cmd-norm"/>
</emission>
</animation>
</syntaxhighlight>

<syntaxhighlight lang="xml">
<animation>
<type>select</type>
<object-name>FlapGauge</object-name>
<condition>
<value alias="../../../params/show-flap-gauge"/>
</condition>
</animation>
</syntaxhighlight>

<syntaxhighlight lang="xml">
<animation>
<type>pick</type>
<object-name>AdjustFreqBigUp</object-name>
<action>
<button>0</button>
<binding>
<command>property-adjust</command>
<property alias="../../../../params/standby-mhz"/>
<value>1</value>
</binding>
</action>
</animation>
</syntaxhighlight>

Even [[Nasal]] scripts can be aliased!

<syntaxhighlight lang="xml">
<animation>
<type>pick</type>
<object-name>BigRedButton</object-name>
<action>
<button>0</button>
<binding>
<command>nasal</command>
<script alias="../../../../params/do-something-exciting-script"/>
</binding>
</action>
</animation>
</syntaxhighlight>

[[Category:Aircraft enhancement|Model with parameters]]
[[Category:Howto|Model with parameters]]

Scripted Compilation on Linux Debian/Ubuntu

2026-03-08T11:38:08Z

Rominet: /* ccache */ Update section

<tt>download_and_compile.sh</tt> is a Bash script that takes care of downloading and compiling FlightGear and related software from their source code repositories with just one command execution for both 32-bit and 64-bit [https://www.debian.org/ Debian]-based systems. Pre-existing versions (if any) of the software installed by <tt>download_and_compile.sh</tt> are not touched at all since the script downloads, builds and installs everything under the directory in which it is launched. You can choose the particular components to download, build and install.

Unless told not to do so, <tt>download_and_compile.sh</tt> installs packages with <tt>apt-get</tt>. For this reason, it is primarily useful on Debian-based distributions. However, if one disables package installation (using <code>-pn</code> or <code>--sudo=echo</code>) and installs the corresponding dependencies oneself, it can be used on other Unix-like systems such as [https://fedoraproject.org/ Fedora Linux], [https://archlinux.org/ Arch Linux] or [https://www.openbsd.org/ OpenBSD].

== Introduction ==

<tt>download_and_compile.sh</tt> is a [https://www.gnu.org/software/bash/ Bash] script written for [https://www.debian.org/ Debian]-derived distributions ([https://www.ubuntu.com/ Ubuntu], [https://devuan.org/ Devuan], [https://www.linuxmint.com/ Linux Mint], etc.). Its purpose is to automatically install dependencies using the package manager, then build and install FlightGear-related programs.

By default, <tt>download_and_compile.sh</tt> installs most dependencies with <tt>apt-get</tt> run under <tt>sudo</tt>.<ref name="disabling-installation-of-dependencies-via-package-manager">If you think you already have the dependencies, this installation can be disabled either by using option <code>-pn</code> or by passing option <code>--sudo=echo</code> (the latter results in printing the <tt>apt-get</tt> command line without running it).</ref> Other dependencies, either because they aren't available in the standard APT repositories, or because of non-option arguments passed to <tt>download_and_compile.sh</tt>, are downloaded and compiled on the fly (this can be the case for [[PLIB]], [[Simgear]] and [[OpenSceneGraph]], for instance—it all depends on the arguments passed to the script).

<tt>download_and_compile.sh</tt> works in the directory it is run from: apart from dependencies installed via the package manager, all programs built by <tt>download_and_compile.sh</tt> are installed under the <tt>install</tt> subdirectory of the directory from which the script was run. In other words, installation of programs by <tt>download_and_compile.sh</tt> is clean, very easy to undo and doesn't interfere with other programs on the system.

It is possible to manage several directory trees with <tt>download_and_compile.sh</tt>; as far as it is concerned, such directory trees are completely independent from each other. For instance, if you run <tt>download_and_compile.sh</tt> in <tt>dir1</tt> and <tt>dir2</tt>, the programs installed under <tt>dir1</tt> won't “see” those installed under <tt>dir2</tt>, and vice versa.

Apart from its main purpose, <tt>download_and_compile.sh</tt> can be used to find hopefully up-to-date build-dependency information for FlightGear and related software. You would do so by inspecting {{fgmeta source
| path = download_and_compile.sh
| text = the script
}} at the point where it installs packages.<ref name="note-inspecting-download-and-compile-sh-to-gather-build-dependency-information">Look for strings such as <tt>zlib1g-dev</tt>, <tt>libglew-dev</tt> or <tt>qt5-default</tt>.</ref>

== Prerequisites ==

Before embarking on building your own FlightGear binaries, you need to install a few tools that <tt>download_and_compile.sh</tt> uses to retrieve and compile source code. These tools are found in the following packages on [https://www.debian.org/ Debian] systems (and presumably on most Debian derivatives too):

* build-essential
* git
* cmake

These packages can be installed by running a command such as:
$ sudo apt-get install build-essential git cmake
Once this is done, the <tt>download_and_compile.sh</tt> script can be run. Unless told otherwise, it will install additional tools and libraries as it runs, depending on the chosen components (this will be explained in further sections).

== Disk space requirements and build time ==

As of April 2019, building FlightGear requires about 12 [https://en.wikipedia.org/wiki/Gibibyte GiB] of disk space. Note that this includes downloaded source code for [[SimGear]] and FlightGear, generated build files and the large [[FGData]] repository (about 6 GiB for that one).

With an Intel Core i7 860 CPU (2.80 GHz) purchased in 2009, compiling [[SimGear]] and FlightGear 2019.2 with option <code>-j8</code> takes about 14 minutes. If you don't have a fast machine and build using only one core, it may require several hours.

== Download ==

You can get <tt>download_and_compile.sh</tt> {{fgmeta source
| path = download_and_compile.sh
| text = from FGMeta
}}. It is contained in the [[FGMeta]] repository, which is maintained by the FlightGear developers. The script can be downloaded from the link given above, however, for easier updates and in order to have the command <code>download_and_compile.sh --version</code> work as intended, it is recommended to get it as explained [[#getting-download-and-compile-sh-using-an-fgmeta-clone|below]].

In case you build stable versions of FlightGear using either of the <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> options of <tt>download_and_compile.sh</tt>, remember to update the script before trying to build a new version of FlightGear (see [[#updating-download-and-compile-sh-using-an-fgmeta-clone|Updating <tt>download_and_compile.sh</tt>]] below). Of course, you can update it more often in order to benefit from new features or bug fixes; this is especially useful if you are building ''next''—that is, the development branch of FlightGear.

== Getting started with <tt>download_and_compile.sh</tt> ==

=== For the impatient ===

So, you're in a hurry, want to build FlightGear but don't want to read any explanation? You can try what follows, but be aware that you may need to come back and read part of the the following sections if you encounter a problem. All commands should be run under a normal user account; however, unless you pass option <code>-pn</code> or something similar to disable installation of packages from your distribution, you'll be asked for your <tt>sudo</tt> password during execution of the <tt>download_and_compile.sh</tt> command (<tt>sudo</tt> is used by <tt>download_and_compile.sh</tt> to run commands like <tt>apt-get</tt>). So, here is your quick recipe for getting <tt>download_and_compile.sh</tt> and using it to build FlightGear:
mkdir -p ~/flightgear/dnc-managed
cd ~/flightgear
{{fgmeta clone | protocol = https}}
cd ~/flightgear/dnc-managed
~/flightgear/fgmeta/download_and_compile.sh -s -j$(nproc)
./run_fgfs.sh --launcher

The <code>-s</code> option passed to <tt>download_and_compile.sh</tt> instructs it to build the latest stable release of FlightGear. Use option <code>--lts</code> instead if you want the latest Long Term Stable release (it may be older but possibly more stable), or <code>--old-lts</code> for the previous LTS release. If you pass none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, <tt>download_and_compile.sh</tt> will build the ''next'' suite, which contains the development version of FlightGear. For more details on these options, see [[#Release selection|Release selection]].

The command <tt>run_fgfs.sh --launcher</tt> starts the [[FlightGear Qt launcher|FlightGear built-in launcher]]. This is often convenient but not compulsory. Another way to start FlightGear could be <code>./run_fgfs.sh --airport=PHTO --aircraft=c172p</code>. There are plenty of other options, which are listed by <code>./run_fgfs.sh --help --verbose</code>.

In some cases, <tt>download_and_compile.sh</tt> stops and waits for your answer before continuing. This is done when there is something important that you should know. When you are used to these prompts and would rather not see them anymore, pass the <code>--non-interactive</code> option to suppress them.

More detailed instructions are given below. The following sections also explain how to update <tt>download_and_compile.sh</tt> and FlightGear.

=== Notations ===

When a command should be run as an unpriviledged user, it will be preceded by a dollar sign:
$ whoami
toto
In contrast, a hash sign (#) means that the command must be run with superuser privileges to achieve the desired effect:
# whoami
root

In order to make instructions easy to understand, two directories (= folders) will be consistently used for the same purpose below:
* <tt>~/flightgear/fgmeta</tt> will contain a clone of the [[FGMeta]] repository; therefore, <tt>download_and_compile.sh</tt> will reside in that directory;
* <tt>~/flightgear/dnc-managed</tt> will be the directory from which we run <tt>download_and_compile.sh</tt>. In other words, with this setup, a typical sequence of commands could be:
$ cd ~/flightgear/dnc-managed
$ ~/flightgear/fgmeta/download_and_compile.sh
or
$ cd ~/flightgear/dnc-managed
$ ~/flightgear/fgmeta/download_and_compile.sh CARES PLIB SIMGEAR FGFS DATA OSG
These are of course just examples. The aforementioned paths are not hardwired anywhere in the script; you are free to choose the directories you want for these purposes.

=== Getting <tt>download_and_compile.sh</tt> the “right way” ===

There are several ways to obtain {{fgmeta source
| path = download_and_compile.sh
| text = download_and_compile.sh
}}. The method described here makes it very easy to update the script and causes the command <code>download_and_compile.sh --version</code> to work as intended.

As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we want to clone the [[FGMeta]] repository in <tt>~/flightgear/fgmeta</tt> and work with its ''next'' branch. Let's go:
$ mkdir -p ~/flightgear
$ cd ~/flightgear
$ {{fgmeta clone | protocol = https}}
You now have a fresh FGMeta clone in <tt>~/flightgear/fgmeta</tt> and your brand new <tt>download_and_compile.sh</tt> script is located in that directory. You can already try it to see the available options:
<pre>$ ~/flightgear/fgmeta/download_and_compile.sh --help
download_and_compile.sh [OPTION...] [--] [COMPONENT...]
Download and compile components belonging to the FlightGear ecosystem.

Without any COMPONENT listed, or if ALL is specified, recompile all
components listed in the WHATTOBUILDALL variable. Each COMPONENT may
be one of the following words:

ALL, ATCPIE, CARES, CMAKE, DATA, FFGO, FGFS, FGRUN, FGX, OPENRADAR, OPENRTI, OSG, PLIB, SIMGEAR, TERRAGEAR, TERRAGEARGUI, ZLIB.

Available options:
-h, --help show this help message and exit
--version print version and license information, then exit

(...)</pre>

=== Updating <tt>download_and_compile.sh</tt> ===

Now that you have <tt>download_and_compile.sh</tt> from the [[FGMeta]] repository, it is very easy to update (this assumes you didn't modify anything yourself inside <tt>~/flightgear/fgmeta</tt>!):
$ cd ~/flightgear/fgmeta && git pull

If you want to keep updates as easy as we just showed, it is best not to modify <tt>download_and_compile.sh</tt> yourself. <tt>download_and_compile.sh</tt> has plenty of options that usually make it unnecessary to modify the script. Just run <code>download_and_compile.sh --help</code> and learn about the available options when you feel the need to change something. Unless you have special needs that can only be accomodated by modifying <tt>download_and_compile.sh</tt>, you are invited to skip to the next section.

If you really, ''really'' want to modify <tt>download_and_compile.sh</tt> while keeping updates easy, a good technique is to add your changes to your FGMeta clone in the form of one or more Git ''commits'' (no need to push them anywhere, commits can remain in your clone). How to do that is beyond the scope of this document, though; read Git tutorials if you want to learn it (there are plenty on the Internet). Once you have committed your changes to your FGMeta clone, make sure the repository is clean (use <code>git status</code>), then update it with:
$ cd ~/flightgear/fgmeta && git pull --rebase
This will apply your commits on top of the latest commit of the branch that is currently checked out, which so far contained the official version of <tt>download_and_compile.sh</tt>. In case your changes conflict with the update, Git will tell you and you'll have to resolve the conflict manually (look for “Git resolve conflict” on your favorite search engine)... or start again from a pristine [[FGMeta]] clone.

=== Building FlightGear ===

In what follows, we won't give the full path to <tt>download_and_compile.sh</tt> when showing commands to be run, but you should prepend it to <tt>download_and_compile.sh</tt> whenever you see a <tt>download_and_compile.sh</tt> command. For instance, if you used the same path as in [[#getting-started-with-download-and-compile-sh-notations|Notations]] and see the command:
$ download_and_compile.sh --help
what you should actually run is:
$ ~/flightgear/fgmeta/download_and_compile.sh --help

Apart from this harmless command, ''do not'' run other <tt>download_and_compile.sh</tt> commands from an arbitrary directory, in particular ''don't'' run them from <tt>~/flightgear/fgmeta</tt>. This is because '''most other <tt>download_and_compile.sh</tt> commands write to the current directory''' (<code>download_and_compile.sh --help</code> and <code>download_and_compile.sh --version</code> are safe to run from any directory, though).

Of course, it is always possible to make commands shorter by setting up aliases (see tips at the end of [https://sourceforge.net/p/flightgear/mailman/message/36634426/ this message]), by adding the directory containing <tt>download_and_compile.sh</tt> to your <tt>PATH</tt> or by creating a symbolink link pointing to <tt>download_and_compile.sh</tt> in a directory that is part of your <tt>PATH</tt>. This is not necessary, though; do it only if you feel the need (when enabled, persistent shell history is often enough to obviate the need to extend the <tt>PATH</tt>).

{{Note|The following commands should be run from an empty directory<ref name="dedicated-directory-won-t-stay-empty-forever">Well, empty before the first time; later, <tt>download_and_compile.sh</tt> is going to populate it with plenty of FlightGear files and subdirectories, of course.</ref> in a partition that has enough free space (see [[#disk-space-requirements-and-build-time | Disk space requirements and build time]]). As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we are going to choose the directory <tt>~/flightgear/dnc-managed</tt> for this purpose, in order to express that the whole directory tree is managed by <tt>download_and_compile.sh</tt>. This is just an example; feel free to choose another directory if you want.

'''Don't run the commands from a non-dedicated directory,''' because it will be filled with files and directories created by <tt>download_and_compile.sh</tt> and the FlightGear, SimGear, etc. build systems. That would be a complete mess! In particular, ''don't'' run the commands from the directory containing your [[FGMeta]] clone.}}

{{Tip|For some commands, <tt>download_and_compile.sh</tt> may use <tt>sudo</tt>. In case you want to run some other program instead of <tt>sudo</tt>, this can be done with the <code>--sudo</code> option of <tt>download_and_compile.sh</tt>. For instance, in order to see the commands that would be run with sudo without actually running them, you can pass <code><nowiki>--sudo=echo</nowiki></code> to <tt>download_and_compile.sh</tt>. Like all other options, <code>--sudo</code> must be given ''before'' all arguments that are component names (such as <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt>, etc.).}}

The package manager used by <tt>download_and_compile.sh</tt> by default is <tt>apt-get</tt> (it won't be used if you pass <tt>download_and_compile.sh</tt> the <code>-pn</code> option). You can use another one if you wish, as long as it supports the following calls:
''pkg-mgr'' update
''pkg-mgr'' install ''pkg1 pkg2'' ...
This is the case for <tt>aptitude</tt> as well as <tt>apt</tt>. If you want <tt>download_and_compile.sh</tt> to use <tt>aptitude</tt>, give it the option <code><nowiki>--package-manager=aptitude</nowiki></code> before any of the ''COMPONENT'' arguments.

All options of <tt>download_and_compile.sh</tt> can be seen by running the following command:
$ download_and_compile.sh --help

Now the instructions. '''You have chosen a dedicated directory''' where all the stuff that is downloaded and built by <tt>download_and_compile.sh</tt> will be stored. This is <tt>~/flightgear/dnc-managed</tt> if you followed the suggestions given in [[#getting-started-with-download-and-compile-sh-notations|Notations]], and should be empty before you run <tt>download_and_compile.sh</tt> for the first time. However, it is quite correct to start <tt>download_and_compile.sh</tt> from the same directory for subsequent runs, even when non-empty (otherwise, <tt>download_and_compile.sh</tt> would automatically reclone the repositories every time you run it; that would be a sheer waste of time and bandwidth). All that remains to do is to run:
$ mkdir -p ~/flightgear/dnc-managed
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh -s -j$(nproc)
The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

{{Note|Because of the <code>-s</code> option, the above <tt>download_and_compile.sh</tt> command would build the latest stable release of FlightGear. If you want to build the latest Long Term Stable release, use <code>--lts</code> instead. For the previous LTS release, use <code>--old-lts</code>. If you want to build the development version of FlightGear, use none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, but be warned: it may very well be unstable and unsuitable for flying. For more details on these options, see [[#Release selection|Release selection]].}}

When you don't pass any non-option argument to <tt>download_and_compile.sh</tt> as done here, it takes care of the base components needed to run FlightGear in good conditions: <tt>CARES</tt>, <tt>PLIB</tt>, <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> (these are the component names used by <tt>download_and_compile.sh</tt>, i.e., the final arguments one can optionally give in a <tt>download_and_compile.sh</tt> command; in normal speech, they correspond to the {{github source
| proj = c-ares
| repo = c-ares
| text = c-ares
}}, {{sourceforge source
| proj = libplib
| repo = code
| text = PLIB
}}, {{simgear source
| text = SimGear
}}, {{flightgear source
| text = FlightGear
}} and {{fgdata source
| text = FGData
}} repositories, as well as a suitable repository for [[OpenSceneGraph]]). Therefore, the above command is presently exactly equivalent to:
$ download_and_compile.sh -s -j$(nproc) CARES PLIB SIMGEAR FGFS DATA OSG

In case you want to build another component such as, say, CMAKE, you can add it to the command, like this:
$ download_and_compile.sh -s -j$(nproc) CARES PLIB SIMGEAR FGFS DATA OSG CMAKE

When the command terminates, you should have a script called <tt>run_fgfs.sh</tt> in the directory from which you ran <tt>download_and_compile.sh</tt> (i.e., <tt>~/flightgear/dnc-managed</tt> in the suggested setup). This will be your script to run FlightGear. For instance, in order to start the [[FlightGear Qt launcher|built-in launcher]], you can run the following commands:<ref name="no-need-to-change-to-dnc-managed-dir-before-starting-generated-scripts">We give these commands because they are easy to read, but the <code>cd</code> command is not needed if you use the correct path, as in <code>~/flightgear/dnc-managed/run_fgfs.sh --launcher</code>.</ref>
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --launcher
(You may omit the <code>--launcher</code> option; this would simply start FlightGear without any launcher, at the default airport and with the default aircraft.) 
In case you find this tedious to type or have more arguments to pass on a regular basis, you can follow the advice given at the end of [https://sourceforge.net/p/flightgear/mailman/message/36634426/ this message] or use another launcher such as [[FFGo]]—but the [[FlightGear Qt launcher|FlightGear built-in launcher]] started with <code>run_fgfs.sh --launcher</code> is quite fine, be sure to try it first!

{{Note|If you ran <tt>download_and_compile.sh</tt> from <tt>~/flightgear/dnc-managed</tt> as proposed above, the full path of the <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> directory is your [[$FG_ROOT]]. This is a very important path for FlightGear; knowing this may be useful for troubleshooting or doing “advanced things.”}}

=== Updating FlightGear ===

{{Note|If you built FlightGear with either of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>, you need to pass the ''same option'' to the <tt>download_and_compile.sh</tt> command given below that will update your FlightGear installation. Otherwise, <tt>download_and_compile.sh</tt> will automatically build the ''next'' suite (bleeding-edge development version), which is probably not what you wish. Moreover, if you do want to switch from one suite to another (for instance from ''stable'' to ''next'', or from ''Long Term Stable'' to ''stable''), using the <code>--cleanup</code> option of <tt>download_and_compile.sh</tt> is heartily recommended.}}

Keeping the above note in mind, go to the directory from which you previously ran <tt>download_and_compile.sh</tt> (<tt>~/flightgear/dnc-managed</tt> in the [[#Notations|suggested setup]]). This is the folder which, if you did a complete run of <tt>download_and_compile.sh</tt> as shown in the previous section, contains the <tt>run_fgfs.sh</tt> script and a log file named <tt>compilation_log.txt</tt> that records what <tt>download_and_compile.sh</tt> did in its last run. If you wish to update, say, {{simgear source
| text = SimGear
}}, {{flightgear source
| text = FlightGear
}}, {{fgdata source
| text = FGData
}} and [[OpenSceneGraph|OSG]], simply execute this:
$ download_and_compile.sh -I -pn -j$(nproc) SIMGEAR FGFS DATA OSG
The <code>-I</code> option tells <tt>download_and_compile.sh</tt> to ignore inter-component dependencies. If you don't use it, other components may be processed too due to these dependencies. The purpose of the behaviour without <code>-I</code> is to help people who aren't necessarily aware of new requirements as time goes (e.g., SIMGEAR and FGFS started to require CARES by the end of 2024; a FlightGear fork of OSG is also required for FGFS ''next'' in 2025). However, it may be frustrating to specify a list of components and see additional ones being automatically added, hence the option.

The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

<tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> are called ''components'' in <tt>download_and_compile.sh</tt> terminology. A component generally corresponds to a software repository, or something close.

Now about the <code>-pn</code>. It is equivalent to <code>-p n</code> and means “don't try to install or update packages from my (Linux) distribution” (<code>y</code> means ''yes, please install or update'', <code>n</code> means ''no, please don't''). In case you forgot that, simply run:
$ download_and_compile.sh --help
What does it imply to pass <code>-pn</code>? This tells <tt>download_and_compile.sh</tt> to completely skip the step where it checks for needed packages from your distribution and installs/updates them, by default using <tt>apt-get</tt>. It thus goes straight to the following steps:
* update each repository corresponding to one of the selected components (<tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt> and <tt>OSG</tt> in our example);
* compile each selected component that requires compilation;
* install each selected component in the appropriate place (under <tt>~/flightgear/dnc-managed</tt> according to our [[#getting-started-with-download-and-compile-sh-notations|Notations]]).
In case you don't have all required dependencies for the selected components, one of them is likely to fail, of course, since by passing <code>-pn</code> to <tt>download_and_compile.sh</tt>, you forbid it to install these dependencies for you. So, you can also very well update without passing the <code>-pn</code> option, it will simply take a little longer (the time to check if all dependencies of the selected components are available with <tt>APT</tt>). In fact, this is '''what you should do if the previous <tt>download_and_compile.sh</tt> run failed:''' first update <tt>download_and_compile.sh</tt> (see [[#getting-download-and-compile-sh-using-an-fgmeta-clone|above]]) then run it ''without'' <code>-pn</code><ref name="passing-no-pn-option-equals-passing-py">Which is the same as passing <code>-py</code>.</ref> in case new dependencies have been recently added and you don't have them on your system yet—this would be a very likely cause for the failure. In this case, running <code>download_and_compile.sh --cleanup</code> to restart the build from a clean state is probably a good idea (see [[#Cleaning built and installed files|Cleaning built and installed files]] for details on this option).

'''Summary'''

Routine update:
$ download_and_compile.sh -pn -j$(nproc) ''COMPONENT...''
(add <code>-I</code> if you don't want inter-component dependencies to pull additional components). In case this fails, first update <tt>download_and_compile.sh</tt> (see [[#getting-download-and-compile-sh-using-an-fgmeta-clone|above]]), then run
$ download_and_compile.sh --cleanup
$ download_and_compile.sh -j$(nproc) ''COMPONENT...''
where ''COMPONENT...'' stands for the space-separated list of components you want <tt>download_and_compile.sh</tt> to process.

=== Examining the history of <tt>download_and_compile.sh</tt> ===

Looking at the latest commits that affected <tt>download_and_compile.sh</tt> is quite easy with your FGMeta clone:
$ cd ~/flightgear/fgmeta
$ git log -- download_and_compile.sh
(then quit by typing <tt>q</tt>, assuming your <tt>$GIT_PAGER</tt> is <tt>less</tt>) 

In order to do the same, but also see the patch for each commit:
$ cd ~/flightgear/fgmeta
$ git log -p -- download_and_compile.sh

=== For the curious: the SSH way ===

{{Note|The method described below is not necessary anymore since {{fgmeta commit | 420034d5b51ff2d32fc0c3716b17a2d862841e0f}} (May 2020). Also, it was written at a time where the canonical location for [[FGData]] was at SourceForge; however, in 2025, the canonical location for FGData is {{fgdata source
| text = here
}}.}}

The purpose of this section is to teach you how to clone [[FGData]] using SSH, then change the Git remote setup in your clone of that repository to retrieve further updates using https—which is convenient, as it does not require you to provide a password. This technique used to be necessary to securely retrieve FGData because of a problem in the [https://sourceforge.net/ SourceForge] infrastructure (namely, <code>git clone</code> from SourceForge doesn't work for the big FGData repository using https). This is not needed anymore in 2025.

Because the following method will make you connect to [https://sourceforge.net/ SourceForge] using the SSH protocol, you'll need an account on that site. If you don't already have one, go to the [https://sourceforge.net/user/registration registration page] and create an account. In all this section, we'll assume that your account name at SourceForge is ''SFusername''.

{{Note|As explained in [[#getting-started-with-download-and-compile-sh-notations|Notations]], we assume that your Unix user name (login) is <tt>toto</tt>. Don't confuse the <tt>sudo</tt> password prompt (where you need to enter <tt>toto</tt>'s password) with the password prompt for your SourceForge account! The former appears as
[sudo] password for toto:
whereas the latter is just:
Password:
}}

{{Tip|For some commands, <tt>download_and_compile.sh</tt> may use <tt>sudo</tt>. In case you want to run some other program instead of <tt>sudo</tt>, this can be done with the <code>--sudo</code> option of <tt>download_and_compile.sh</tt>. For instance, in order to see the commands that would be run with sudo without actually running them, you can pass <code><nowiki>--sudo=echo</nowiki></code> to <tt>download_and_compile.sh</tt>. Like all other options, <code>--sudo</code> must be given ''before'' all arguments that are component names (such as <tt>SIMGEAR</tt>, <tt>FGFS</tt>, <tt>DATA</tt>, etc.).}}

{{Note|The commands given below will build the ''next'' suite, which contains the bleeding-edge development version of FlightGear. This is likely to be unstable, possibly unsuitable for flying. If you'd rather build the latest stable release or the latest Long Term Stable release, add option <code>-s</code> or <code>--lts</code> to all <tt>download_and_compile.sh</tt> commands given below (or <code>--old-lts</code> for the previous LTS release). You may add the chosen option right after the <tt>download_and_compile.sh</tt> command name (in any case, the option should come before non-option arguments such as SIMGEAR, FGFS, DATA, etc.). See [[#Release selection|Release selection]] for more explanations on options <code>-s</code>, <code>--lts</code> and <code>--old-lts</code>.}}

Now the instructions. You have chosen a dedicated directory where all the stuff that is downloaded and built by <tt>download_and_compile.sh</tt> will be stored. This is <tt>~/flightgear/dnc-managed</tt> in our example, and should be empty before you run <tt>download_and_compile.sh</tt> for the first time. However, it is quite correct to start <tt>download_and_compile.sh</tt> from the same directory for subsequent runs, even when non-empty (otherwise, <tt>download_and_compile.sh</tt> would automatically reclone the repositories every time you run it; that would be a sheer waste of time and bandwidth).

Ready? Let's go!
<pre>$ mkdir -p ~/flightgear/dnc-managed
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
Fetching DATA with 'git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata'
Cloning into '.'...
The authenticity of host 'git.code.sf.net (216.105.38.16)' can't be established.
ECDSA key fingerprint is SHA256:FeVkoYYBjuQzb5QVAgm3BkmeN5TTgL2qfmqz9tCPRL4.
Are you sure you want to continue connecting (yes/no)?
Warning: Permanently added 'git.code.sf.net,216.105.38.16' (ECDSA) to the list of known hosts.
Connection closed by 216.105.38.16 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
</pre>

The above messages are perfectly normal but deserve a little explanation. Here, <tt>ssh</tt> asked us to confirm that the fingerprint sent by the remote host is that of the real <tt>git.code.sf.net</tt>, as opposed to that of some malicious server ''pretending'' to be <tt>git.code.sf.net</tt>. This confirmation only has to be done once, after which it is remembered thanks to <tt>~/.ssh/known_hosts</tt>. You should visit the [https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/#fingerprint-listing page that gives the host key fingerprint of every publically-accessible SSH server at SourceForge] and carefully check that the fingerprint appearing on your terminal is listed on that page for <tt>git.code.sf.net</tt>, or some matching pattern such as <tt>*.code.sf.net</tt>.

If the fingerprint that is printed on your terminal is not listed on that page, answer <tt>no</tt> to the question ''Are you sure you want to continue connecting (yes/no)?'' and copy/paste to flightgear-devel (see [[Mailing lists]]) the above message from <tt>ssh</tt> that contains the fingerprint sent to you by the remote host which pretends to be <tt>git.code.sf.net</tt>. If this happened, you should stop here and wait for answers from readers of flightgear-devel.

From now on, we'll assume that the fingerprint you received was correct, and therefore that you have answered <tt>yes</tt> to the ''Are you sure you want to continue connecting (yes/no)?'' question.

In this example, it took us several minutes to verify the fingerprint of the <tt>git.code.sf.net</tt> server and confirm it to <tt>ssh</tt>. Because of this delay, <tt>git.code.sf.net</tt> hung up on us and closed the connection. This is absolutely ''not a problem:'' we can just rerun the <tt>download_and_compile.sh</tt> command with the same arguments as the first time. Since we answered <tt>yes</tt> to the ''Are you sure you want to continue connecting (yes/no)?'' prompt, the fingerprint of <tt>git.code.sf.net</tt>'s key has been stored in <tt>~/.ssh/known_hosts</tt>, therefore we won't get this prompt anymore. But if some server claiming to be <tt>git.code.sf.net</tt> presents a host key that has a different fingerprint in the future, <tt>ssh</tt> will print a big fat warning that the server may belong to an attacker trying to impersonate <tt>git.code.sf.net</tt>. Therefore, this SSH host key verification is very useful to protect us from future attacks (which hopefully won't happen at all).

As said, we just rerun the <tt>download_and_compile.sh</tt> command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
Fetching DATA with 'git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata'
Cloning into '.'...
Password:</pre>
As explained above, the preceding prompt is for your SourceForge password (which you could guess from the <code><nowiki>git clone ssh://SFusername@git.code.sf.net/p/flightgear/fgdata</nowiki></code> command).
<pre>remote: Enumerating objects: 67011, done.
remote: Counting objects: 100% (67011/67011), done.
remote: Compressing objects: 100% (31342/31342), done.
remote: Total 67011 (delta 38776), reused 59640 (delta 33570)
Receiving objects: 100% (67011/67011), 2.60 GiB | 313.00 KiB/s, done.
Resolving deltas: 100% (38776/38776), done.
Checking out files: 100% (12959/12959), done.
Password:</pre>
(It will take a fair amount of time to get there, because this is the complete download of [[FGData]].) 
This is again a prompt for your SourceForge password, because <tt>download_and_compile.sh</tt> wants to run <code>git pull --rebase</code> in the repository (admittedly, it's a bit dumb after a <tt>clone</tt> operation—please forgive us). In case you were not monitoring the <tt>clone</tt> operation, you probably saw the password prompt way after <tt>git.code.sf.net</tt> got bored waiting for you and closed our second connection:
<pre>Connection closed by 216.105.38.16 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.</pre>
(if not, there should be no error message and you should have a clean FGData clone) 
No worries. Just as before, simply rerun the command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:SFusername DATA
**********************************************************************
* *
* Warning: a typical SimGear + FlightGear + FGData build requires *
* about 12 GiB of disk space. The compilation part may last from a *
* few minutes to hours, depending on your computer. *
* *
* Hint: use the -j option if your CPU has several cores, as in: *
* *
* download_and_compile.sh -j$(nproc) *
* *
**********************************************************************
Running 'apt-get update'...
[sudo] password for toto:

(...)

Considering a package alternative: libcurl4-openssl-dev libcurl4-gnutls-dev
Package alternative matched for libcurl4-openssl-dev
Running 'apt-get install build-essential git libcurl4-openssl-dev cmake'...
[sudo] password for toto:

(...)

****************************************
**************** DATA ******************
****************************************
DATA: the repository already exists
Password:
Already up to date.
Current branch next is up to date.
Already on 'next'
Your branch is up to date with 'origin/next'.
All optional package alternatives have found a matching package.

download_and_compile.sh has finished to work.
</pre>
There we are! You now have a clean, up-to-date [[FGData]] clone in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> (remember: <tt>~/flightgear/dnc-managed</tt> is the directory from which you ran <tt>download_and_compile.sh</tt>). Note this place: the full path of the <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt> directory is your [[$FG_ROOT]].

Now, change the protocol to use for future updates of your FGData clone:<ref name="changing-the-protocol-for-a-git-remote-manual-method">Another way would be to manually change the relevant line starting with <code>url = <nowiki>ssh://SFusername@</nowiki></code> for the <code>origin</code> remote in the <tt>.git/config</tt> file that lives inside your repository clone (i.e., <tt>~/flightgear/dnc-managed/install/flightgear/fgdata/.git/config</tt> in our example).</ref>
(cd install/flightgear/fgdata && \
git remote set-url origin <nowiki>https://git.code.sf.net/p/flightgear/fgdata</nowiki>)
(you can check at any time the protocol(s) in use with the command <code>git remote -v</code> run inside a Git repository—in this case, inside the folder <tt>install/flightgear/fgdata</tt>). As a consequence of this change, all future updates of your FGData clone will use the <tt>https</tt> protocol, therefore you won't be prompted anymore for your SourceForge password.

All that remains to do is to run, from the same directory as before (<tt>~/flightgear/dnc-managed</tt> in our example):
$ download_and_compile.sh -j$(nproc)
The <code>-j$(nproc)</code> option is not necessary, but is likely to save you a lot of time; with it, all available CPU cores will be used when compiling—see [[#Multicore acceleration| Multicore acceleration]].

Assuming the compilation was successful, you can now start the [[FlightGear Qt launcher|FlightGear built-in launcher]] using for instance:
$ ./run_fgfs.sh --launcher
See [[#Building FlightGear|Building FlightGear]] for more details.

== List of available components ==

The <tt>download_and_compile.sh</tt> script is able to download, compile (when applicable) and install the following components:

* ATCPIE (for the [[ATC-pie]] air traffic control simulation program)
* CMAKE (for the [https://cmake.org/ CMake] build tool—this can be useful in case CMake is too old in your distribution)
* DATA (for [[FGData]], the main set of data files used by FlightGear)
* FGFS (for FlightGear itself)
* FFGO (for the [[FFGo]] FlightGear launcher)
* FGRUN (for the [[Fgrun|FGRun]] FlightGear launcher)
* FGX (for the [[FGX|FGx]] FlightGear launcher<ref name="note-on-the-status-of-FGx-support-in-download-and-compile-sh">Support for FGx in <tt>download_and_compile.sh</tt> would probably benefit from a code review.</ref>)
* OPENRADAR (for the [[OpenRadar]] air traffic control simulation program)
* OPENRTI (for [[FlightGear HLA support (High Level Architecture)#OpenRTI | OpenRTI]]<ref name="note-on-the-status-of-OpenRTI-support-in-FG">Note that OpenRTI is just an optional dependency for [[FlightGear high-level architecture support | HLA support]]. For the time being, you should be just fine building without it. Eventually, the idea is for HLA to replace the existing MP system and even increasingly distribute the FlightGear architecture such that more and more components can be more easily run in separate threads or even separate processes, possibly even on different machines. So this is going to be an important feature for professional users, using several computers and screens to create a comprehensive and immersive simulation environment.

At the moment, it is probably safe to say that HLA is only of interest to developers and people willing to play with experimental features.</ref>)
* OSG (for the [[OpenSceneGraph]] library)
* PLIB (for the [[PLIB]] library)
* SIMGEAR (for the [[SimGear]] library—foundation for FlightGear and TerraGear)
* TERRAGEAR (for the [[TerraGear]] terrain building toolchain)
* TERRAGEARGUI (for [[TerraGear GUI]], a graphical interface for TerraGear)
* ZLIB (for the [http://www.zlib.net/ zlib] compression library)

Each of the items listed above is a ''component'' in <tt>download_and_compile.sh</tt> terminology. Components are written in uppercase by convention.

{{Note|The preceding list might not be up-to-date. The up-to-date list of components supported by <tt>download_and_compile.sh</tt> can always be obtained by running <code>download_and_compile.sh --help</code>.}}

What is the point of knowing this? Because you may pass component names to <tt>download_and_compile.sh</tt> in order to tell it what you want to download, build and install. By default, only the components [[SimGear|SIMGEAR]], [[FlightGear|FGFS]], [[FGData|DATA]] and [[OpenSceneGraph|OSG]] are taken care of, which means that the command:
$ download_and_compile.sh
is equivalent to:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

In case you'd like to do the same build with just [[PLIB]] added, you could use:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG PLIB

You get the idea. When several components are passed on the same command line, <tt>download_and_compile.sh</tt> chooses a reasonable order for processing, so don't worry about that.

== When building ''next'', you may encounter problems ==

Keeping in mind that this script compiles sometimes bleeding edge software, it can happen that what was successfully compiling last week, does not compile anymore today. Building the latest stable version (option <code>-s</code>) or the latest Long Term Stable release (option <code>--lts</code>) should always work, unless there is a problem with the script (well, in some cases, there may be packages of your distribution that are too recent for <code>--lts</code>; for instance, in July 2020, <code>--lts</code> didn't build with OpenSceneGraph 3.6, but simply passing the OSG component on the <tt>download_and_compile.sh</tt> command solved the problem, because at that time, option <code>--lts</code> selected OpenSceneGraph 3.4).

That said, you may want to build the development version (called ''next''): this is the one developers use all the time, so kindly asking on the flightgear-devel [[Mailing_lists|mailing list]] in case a problem popped up<ref name="what-to-provide-when-asking-for-help">Don't forget in this case to precisely tell what you did and include the <tt>compilation_log.txt</tt> file written by <tt>download_and_compile.sh</tt>.</ref> should allow you to find good advice and get the problem quickly fixed, if it's a new one.

{{Warning|As of July 2020, heavy development will be done on ''next'', the development branch of FlightGear. It is expected to be rather unstable for several months. Unless you are really interested in FlightGear development or in providing feedback to the developers, you're probably better off building either the latest stable version (option <code>-s</code>) or the latest Long Term Stable release (option <code>--lts</code>). In case you want something even older, the previous LTS release can be selected with option <code>--old-lts</code>.}}

== Task-specific instructions ==

{{Note|In this section, we assume you've read and followed the advice given in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]].}}

=== Selecting the components to build ===

By default, <tt>download_and_compile.sh</tt> downloads or updates, then compiles, [[SimGear]], FlightGear, [[FGData]] and [[OpenSceneGraph|OSG]] (more precisely, FGData is downloaded but not compiled—that wouldn't make sense). This is what happens when running:
$ download_and_compile.sh
The preceding command is therefore equivalent to:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

To make <tt>download_and_compile.sh</tt> take care of other programs or libraries, use non-option arguments naming the ''components'' you want, for instance:
$ download_and_compile.sh SIMGEAR FGFS DATA OSG CMAKE
SIMGEAR, FGFS, DATA, OSG and CMAKE are the component names respectively corresponding to [[SimGear]], FlightGear, [[FGData]], [[OpenSceneGraph]] and [https://cmake.org/ CMake] in <tt>download_and_compile.sh</tt>'s terminology.

A [[#list-of-available-components|list of available components]] is provided on this page, but the fully up-to-date list can always be obtained by running <code>download_and_compile.sh --help</code>.

=== Choosing between stable and development versions ===

By default, <tt>download_and_compile.sh</tt> fetches code and data from development branches of the source repositories (which sometimes causes compilation or runtime errors). However, it is possible to tell the script to download the latest “stable” version of each component, for some suitable definition of “stable”. This is by means of the <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> options:
$ download_and_compile.sh -s ''COMPONENT1 COMPONENT2...''
or
$ download_and_compile.sh --lts ''COMPONENT1 COMPONENT2...''
or
$ download_and_compile.sh --old-lts ''COMPONENT1 COMPONENT2...''

How does it work?
* For [[SimGear]], FlightGear and [[FGData]], <code>-s</code> uses the most recent stable release branch of the corresponding Git repository, <code>--lts</code> uses the most recent Long Term Stable release (LTS) and <code>--old-lts</code> uses the previous LTS release.
* For other components, a known-stable version is selected by <tt>download_and_compile.sh</tt>, which may be influenced by the use of <code>-s</code>, <code>--lts</code> or <code>--old-lts</code>.

So, as far as the SIMGEAR, FGFS and DATA components are concerned, you can:
* build the latest stable release (<code>-s</code>);
* build the latest Long Term Stable release (<code>--lts</code>);
* build the previous Long Term Stable release (<code>--old-lts</code>);
* build the current development version (bleeding edge), which lives in the {{flightgear source
| branch = next
| text = next
}} branch of the FlightGear repository.
The use of <code>-s</code>, <code>--lts</code> or <code>--old-lts</code> also influences the version of other components you may have selected (this can be overridden using <code>--component-branch</code> for advanced users—see [[#Component-specific settings|Component-specific settings]]).

{{Note|In a given folder where <tt>download_and_compile.sh</tt> is run, you should normally either always use the <code>-s</code> option, or always use <code>--lts</code>, or always use <code>--old-lts</code>, or always none of these (in other words, stick to the same suite: latest stable, latest LTS, previous LTS or ''next'', consistently accross all components).}}

Actually, it ''is'' possible to switch between suites but you have to use the <code>--cleanup</code> option when doing the switch (see [[#Cleaning built and installed files|Cleaning built and installed files]] for information on this option). For instance:
* Build with <code>-s</code> as many times as you want.
* Want to try ''next''? Okay, then build once with <code>--cleanup</code> (no <code>-s</code> option anymore).
* You can then perform as many builds of ''next'' as you want; no need to use <code>--cleanup</code> unless something special went wrong.
* If you later decide to switch back to the stable release, build once with <code>-s</code> and <code>--cleanup</code>, then only with <code>-s</code> for further builds.
* etc.

This way, ''you don't need to download the repositories again'' when trying the various suites. In particular, you can switch between ''next'', stable, LTS and old LTS without downloading nor having several copies of [[FGData]] on your hard drive. (This works because a Git repository may internally contain data for several branches, even if only one is “normally visible” in the filesystem at a given time.)

==== Building the latest Long Term Stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>--lts</code> option to build the latest Long Term Stable release:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --lts
(In this example, the implicitly-selected components are SIMGEAR, FGFS and DATA, as explained [[#selecting-the-components-to-work-on | above]].)

{{Note|If you decide to use the <code>--lts</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>--lts</code> option for some components and not for others is not supported.}}

==== Building the latest stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>-s</code> option to build the latest stable release:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh -s

{{Note|If you decide to use the <code>-s</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>-s</code> option for some components and not for others is not supported.}}

==== Building the current FlightGear development version ====

When executing <tt>download_and_compile.sh</tt> without any option, the development version of every selected component is built:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh

{{Note|The development version of FlightGear changes on an almost daily basis. It provides the latest features, but is not guaranteed to always work reliably. If you don't want to take the risk of finding new bugs when updating, you may prefer to use the latest stable release.}}

==== Building the previous Long Term Stable release of FlightGear ====

When executing <tt>download_and_compile.sh</tt>, use the <code>--old-lts</code> option to build the previous Long Term Stable release (i.e., oldish code):
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh --old-lts
(In this example, the implicitly-selected components are SIMGEAR, FGFS and DATA, as explained [[#selecting-the-components-to-work-on | above]].)

{{Note|If you decide to use the <code>--old-lts</code> option in a given directory tree, you should use it for all components in that directory tree (SIMGEAR, FGFS, DATA, etc.). Running <tt>download_and_compile.sh</tt> in a given directory with the <code>--old-lts</code> option for some components and not for others is not supported.}}

=== Overriding the source repository or branch for a component ===

This section shows how to override the location and/or branch from which a given component will be downloaded.

{{Warning|The rest of this section is for people who know what they are doing. Don't use the following unless you trust the person who publishes the repository and have good reasons to believe that it has been kept up-to-date.}}

==== A short example ====

Let's start with an example to make it easier to understand to following paragraphs. Suppose we want to build the current stable release of FlightGear, linked against an [[OpenSceneGraph]] library whose source code is to be retrieved from branch <tt>fgfs-osg-36-2</tt> of the Git repository located at [https://gitlab.com/flightgear/openscenegraph.git https://gitlab.com/flightgear/openscenegraph.git] (this is actually the default in September 2024). Since the default protocol used when <tt>download_and_compile.sh</tt> clones a repository is [https://en.wikipedia.org/wiki/HTTPS HTTPS], this can be done with
download_and_compile.sh --cleanup -s \
--override-repo OSG=GitLab:gitlab.com/flightgear/openscenegraph.git \
--component-branch OSG=fgfs-osg-36-2 SIMGEAR FGFS DATA OSG

==== The site name ====

<tt>download_and_compile.sh</tt> uses case-insensitive short names such as <tt>GitLab</tt>, <tt>GitHub</tt>, <tt>SourceForge</tt> and <tt>gitlab.kitware.com</tt> as keys in order to identify the settings describing where and how a given component will be initially fetched (these settings are effective at clone time; later updates simply use the settings recorded in the local repository). These names are referred to as ''site'' in the output of <code>download_and_compile.sh --help</code>, in particular in the <tt>--git-clone-site-params</tt> and <tt>--override-repo</tt> options we'll present below. These ''site'' keys are simply identifier strings; they are not used in the DNS queries.

==== The protocol ====

Current <tt>download_and_compile.sh</tt> (from December 2022) fetches the source code of most components from Git repositories (earlier versions used Subversion for some components); a few non-core components (currently [[FGo!]] and [[OpenRadar]]) are fetched using <tt>wget</tt> and are out-of-scope for this section.

The default protocol used by <tt>download_and_compile.sh</tt> when cloning a Git repository is [https://en.wikipedia.org/wiki/HTTPS HTTPS]. This can be overridden using the <tt>--git-clone-default-proto</tt> option. In other words, the default is <tt>--git-clone-default-proto=https</tt> (the protocol name is case-insensitive). Other possibilities for the protocol are <tt>git</tt> and <tt>ssh</tt>.

{{Warning|The <tt>git</tt> protocol doesn't protect against man-in-the-middle attacks; use at your own risk! Unfortunately, “clever” people often recommend it on the forum without mentioning its downsides.}}

Using the <tt>ssh</tt> protocol as the argument of <tt>--git-clone-default-proto</tt> has little use, because in general you'll want to specify a particular username when using SSH and this username is likely not to be the same for all components you intend to clone via SSH (right, <tt>~/.ssh/config</tt> can be used to automatically provide a site-dependent username). That is why <tt>download_and_compile.sh</tt> offers the <tt>--git-clone-site-params</tt> option.

==== Site-specific settings ====

Using
--git-clone-site-params ''SITE''=''PROTOCOL''[:''USERNAME'']
you can tell <tt>download_and_compile.sh</tt> that every component fetched from ''SITE'' should be cloned with the specified protocol and username (allowed protocols are <tt>https</tt>, <tt>ssh</tt> and <tt>git</tt>).

{{Note|In case you have several repositories at a given site (say, GitHub) and need to use different SSH usernames for these repositories, you can use different site names:
<pre>
--override-repo COMPONENT_A=GitHubA:ADDRESS_A
--git-clone-site-params GitHubA=ssh:userA
--override-repo COMPONENT_B=GitHubB:ADDRESS_B
--git-clone-site-params GitHubB=ssh:userB</pre>
Here, the site names are <tt>GitHubA</tt> and <tt>GitHubB</tt>; the <tt>--override-repo</tt> option will be presented below.

By default, <tt>download_and_compile.sh</tt> case-insensitively uses the <tt>GitLab</tt> (resp. <tt>SourceForge</tt>) site name to identify the settings used when cloning a repository from gitlab.com (resp. git.code.sf.net). Therefore, the settings for GitHubA and GitHubB in this example would only apply to components ''c'' for which --override-repo ''c''<nowiki>=</nowiki>GitHubA:... or --override-repo ''c''<nowiki>=</nowiki>GitHubB:... has been specified.}}

==== Component-specific settings ====

The <tt>--override-repo</tt> and <tt>--component-branch</tt> options allow one to override the default settings used by <tt>download_and_compile.sh</tt> for cloning the repository corresponding to the specified component (they only apply to components whose source code is retrieved with Git). The syntax of these options is
--override-repo ''COMPONENT''=''SITE'':''ADDRESS''
and
--component-branch ''COMPONENT''=''BRANCH''
In this syntax:
* ''COMPONENT'' represents the name of a component for <tt>download_and_compile.sh</tt> (e.g., <tt>SIMGEAR</tt>—see [[#List of available components|List of available components]]);
* ''ADDRESS'' is something like <tt>gitlab.com/flightgear/simgear.git</tt> (don't include any <tt>protocol://</tt> part in ''ADDRESS'');
* ''BRANCH'' should be the name of an existing branch of the Git repository hosted at ''ADDRESS'';
* ''SITE'' is a string used as a key in a mapping; <tt>download_and_compile.sh</tt> uses it to find out how to connect to ''ADDRESS'' in order to clone the repository for ''COMPONENT'' (see [[#Site-specific settings|Site-specific settings]]).
See the [[#A short example|above example]] for a concrete example where these options are used.

{{Note|The argument of any long option of <tt>download_and_compile.sh</tt> that takes an argument may be introduced immediately after the option name using an equal sign. However, in the above cases, I find this way a bit confusing because the option value ''also'' uses an equal sign as separator. Hence the above use of separate command arguments: one for the option name, one for its argument.}}

=== Passing custom arguments to CMake ===

Sometimes, when building a program, you may want to enable a feature that is not enabled by default, or disable a feature that is enabled by default. With recent versions of <tt>download_and_compile.sh</tt> (October 2020 or later), this can be done for SimGear and FlightGear using the <code>--sg-cmake-arg</code> and <code>--fg-cmake-arg</code> options (the environment variables <tt>SG_CMAKEARGS</tt> and <tt>FG_CMAKEARGS</tt> are still supported, but they don't allow one to pass arguments containing spaces). For instance, in order to link SimGear with the system Expat library, you can do:
$ download_and_compile.sh --sg-cmake-arg='-DSYSTEM_EXPAT=ON' SIMGEAR
Similarly, disabling HID-based input when building FlightGear can be achieved this way:
$ download_and_compile.sh --fg-cmake-arg='-DENABLE_HID_INPUT=OFF' FGFS

{{Note|Such options are typically defined in <tt>CMakeLists.txt</tt> files, for example {{simgear source
| path = CMakeLists.txt
| text = here
}} for SimGear and {{flightgear source
| path = CMakeLists.txt
| text = here
}} for FlightGear.}}

This can be useful, for instance, to work around bugs in a part of SimGear or FlightGear that you don't need, but causes a build or runtime failure (see {{forum link|t=35740|text=here}} for example). This is often convenient when using the development version of FlightGear, but doesn't mean such bugs shouldn't be reported!

If you have several such options to pass, just use <code>--sg-cmake-arg</code> and/or <code>--fg-cmake-arg</code> several times:
$ download_and_compile.sh --fg-cmake-arg='-DENABLE_SWIFT=ON' \
--fg-cmake-arg='-DENABLE_HID_INPUT=OFF' FGFS
It is even possible to pass arguments containing spaces to CMake, as in:
$ download_and_compile.sh \
--sg-cmake-arg='-DCMAKE_CXX_FLAGS=-Wno-deprecated-declarations -Wall' \
SIMGEAR
(just a silly example to show a working syntax) or:
$ download_and_compile.sh \
--fg-cmake-arg="-DCMAKE_CXX_FLAGS=$(pkg-config --cflags gl)" \
FGFS
Note the use of double-quotes here to enable the <code>$(...)</code> command substitution.

Using the (half-deprecated) environment variables <tt>SG_CMAKEARGS</tt> and <tt>FG_CMAKEARGS</tt>, it is also possible to define CMake arguments in a single place that are going to be used for both SimGear and FlightGear. However, this technique doesn't allow one to pass arguments containing spaces to CMake.
$ export SG_CMAKEARGS='-DSYSTEM_EXPAT=ON'
$ export FG_CMAKEARGS='-DENABLE_SWIFT=ON -DENABLE_HID_INPUT=OFF'
$ download_and_compile.sh

=== Seeing the compilation commands run by Make ===

As a simple application of the previous section, the following options are often useful. When passed to <tt>download_and_compile.sh</tt>, these options cause the compilation commands run via Make to be printed on the terminal and recorded in the compilation_log.txt file:
--sg-cmake-arg='-DCMAKE_VERBOSE_MAKEFILE=1' \
--fg-cmake-arg='-DCMAKE_VERBOSE_MAKEFILE=1'
(the backslash is unneeded if you put both options on the same line). Passing the value 0 instead of 1 would explicitly request the default, non-verbose behavior.

=== Launching FlightGear ===

When using <tt>download_and_compile.sh</tt>, apart from those installed with the package manager, the FlightGear dependencies (which are typically libraries) are not installed system-wide but under the directory from which <tt>download_and_compile.sh</tt> was run. This makes it possible to easily use, for instance, different [[OpenSceneGraph]], [[SimGear]] and FlightGear versions on a single system—e.g., for testing purposes—but also to have separate build trees (optimized/debug). This is also why you either need to set LD_LIBRARY_PATH to run the built programs, or simply use the scripts created by <tt>download_and_compile.sh</tt> in the directory where it is run, such as <tt>run_fgfs.sh</tt> and <tt>run_fgfs_debug.sh</tt>: these scripts automatically set up the required environment variables according to your build settings before firing the desired program (e.g., <tt>fgfs</tt>) with the arguments you provided.

Therefore, the simplest way to run a FlightGear program built by <tt>download_and_compile.sh</tt> is to launch the <tt>run_fgfs.sh</tt> script that <tt>download_and_compile.sh</tt> created in the directory from which it was run, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --launcher

{{Note|<code>./run_fgfs.sh --launcher</code> starts FlightGear with its built-in launcher. If you just do <code>./run_fgfs.sh</code>, FlightGear will be started without any launcher, at the default airport and with the default aircraft.}}

In order to start FlightGear without any launcher, at a given airport (say, [https://en.wikipedia.org/wiki/Paro_Airport Paro airport], whose ICAO code is VQPR) and with a chosen aircraft, you can do:
$ cd ~/flightgear/dnc-managed
$ ./run_fgfs.sh --airport=VQPR --aircraft=dhc6
Actually, the directory change is not needed, we only gave it here for readability. Therefore, the following single command does the same:
$ ~/flightgear/dnc-managed/run_fgfs.sh --airport=VQPR --aircraft=dhc6

=== Avoiding multiple downloads of FGData ===

Some people use <tt>download_and_compile.sh</tt> to maintain several directory trees such as the tree starting at <tt>~/flightgear/dnc-managed</tt> in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]] (this can be useful if you want to have one tree with programs compiled in Release mode and another tree where they are built in Debug mode, for instance). This can easily be done by running <tt>download_and_compile.sh</tt> in each of the directories. But since [[FGData]] is so large, it may be tempting to share a single instance of this repository among several trees. This is not officially supported, but apparently can be made to work with symbolic links.

Let's show how this can be done on an example. Suppose your master copy of FGData is in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt>. Then the following appears to work:
$ mkdir -p ~/flightgear/other-dnc-managed-tree/install/flightgear
$ cd ~/flightgear/other-dnc-managed-tree/install/flightgear
$ ln -s ../../../dnc-managed/install/flightgear/fgdata
$ cd ~/flightgear/other-dnc-managed-tree
$ download_and_compile.sh

The last of these commands will use and update the FGData repository present in <tt>~/flightgear/dnc-managed/install/flightgear/fgdata</tt>.

{{Warning|This can only work simply if all trees that share a given FGData repository are from the same release (e.g., current stable or development). Running a “stable“ FlightGear with FGData from the ''next'' branch or the other way round, a development version of FlightGear with FGData from a release branch, doesn't work—and FlightGear should tell you when you start it in such a situation.

That said, people comfortable with Git can check out the correct FGData branch before building or starting FlightGear, for instance:
$ cd /path/to/fgdata && git checkout release/2019.1
or
$ cd /path/to/fgdata && git checkout next
So, this is possible but somewhat acrobatic. You've been warned.}}

Note: there is a [[Avoiding multiple downloads of FGData on Linux|wiki article about this subject]], but it is severely outdated as of April 2019.

== Additional programs ==

{{Note|In this section, we assume you've read and followed the advice given in [[#getting-started-with-download-and-compile-sh|Getting started with <tt>download_and_compile.sh</tt>]].}}

If you wish to get other programs (precisely: download, build and install them), you need to launch <tt>download_and_compile.sh</tt> with the desired component names as arguments. For instance:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh SIMGEAR FGFS DATA OSG

See [[#list-of-available-components|above]] for the list of available components.

=== TerraGear ===

Run <tt>download_and_compile.sh</tt> with the TERRAGEAR component in order to build and install the [[TerraGear]] terrain building toolchain:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh TERRAGEAR

This creates the following scripts in <tt>~/flightgear/dnc-managed</tt>:
* <tt>run_genapts850.sh</tt>
* <tt>run_ogr-decode.sh</tt>
* <tt>run_tg-construct.sh</tt>
These scripts themselves run the corresponding TerraGear tools, as expected.

=== TerraGear GUI ===

[[TerraGear GUI]] is a graphical interface for [[TerraGear]] written with the Qt toolkit (still Qt 4 in 2019, but it works). In order to install it, run <tt>download_and_compile.sh</tt> with the TERRAGEARGUI component:
$ cd ~/flightgear/dnc-managed
$ download_and_compile.sh TERRAGEARGUI
This will create a <tt>run_terrageargui.sh</tt> script in <tt>~/flightgear/dnc-managed</tt>, and also a default configuration file <tt>~/.config/TerraGear/TerraGearGUI.conf</tt>, unless you already have one. This default configuration file contains paths to the TerraGear and [[$FG_ROOT]] directories, assuming you have installed the TERRAGEAR and DATA components.

To run TerraGear GUI:
$ cd ~/flightgear/dnc-managed
$ ./run_terrageargui.sh

=== FGCom ===

{{Note|[[FGCom]] has been integrated into FlightGear long ago, therefore the following is not needed in general.}}

[[FGCom]] is the system used by FlightGear to simulate radio communications between users. It is automatically built and installed when you tell <tt>download_and_compile.sh</tt> to take care of the FGFS component. You can launch the standalone FGCom program by using the <tt>run_fgcom.sh</tt> script:
$ cd ~/flightgear/dnc-managed
$ ./run_fgcom.sh

=== FGRun ===

{{Note|As of 2019, FGRun has been superseded by the [[FlightGear Qt launcher|FlightGear built-in launcher]]. The built-in launcher is the most actively maintained launcher for FlightGear. Other launchers are [[FFGo]] and [[FGX|FGx]].}}

[[File:fgrun-page2.jpg|thumb|right]]
Before FlightGear had its built-in launcher (the one you get with <code>run_fgfs.sh --launcher</code>), many users found comfortable having FlightGear launched by the graphical utility [[Fgrun|FGRun]]. This program is built and installed when <tt>download_and_compile.sh</tt> is run with the FGRUN component. You then have to launch the <tt>run_fgrun.sh</tt> command, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgrun.sh

FGRun will save its settings in <tt>~/.fltk/flightgear.org/fgrun.prefs</tt>. You may want to save copies of the preferences customized for stable and next.

=== FGo! ===

{{Note|As of 2019, FGo! is not maintained anymore. You may want to try the built-in launcher (started with <code>run_fgfs.sh --launcher</code>) or [[FFGo]].}}

[[File:Fgo01.jpg|thumb|left]]
FGo! is a graphical utility written in [[python]]. It is downloaded and installed when <tt>download_and_compile.sh</tt> is run with the FGO component. You then have to launch the <tt>run_fgo.sh</tt> command, for example:
$ cd ~/flightgear/dnc-managed
$ ./run_fgo.sh

Remember that the first time you run it, you have to go to open the ''Preferences'' dialog and set the paths to the <tt>fgfs</tt> executable and to FGData.

== Troubleshooting ==

=== Compilation errors ===
Here we are, no fear, if you wish to use programs from the cvs/svn/git repositories, you might face compilation errors that will prevent you to have a working copy of one or more of the programs provided by this script. What can be the causes that prevent us from successfully compiling? As far as I know those:
# Software developers introduce a new functionality with a new piece of code that prevents the compilation under your architecture, this can happen working with cvs/svn/git sources.
# The program refuses to compile because of a divergence in the libraries on which it depends. For example FlightGear might not compile because OSG has been modified, while OSG itself compiles fine, FG won't.
# One or more repositories are down and you can't get the library you need. (Both from cvs/svn/git or apt-get)

There is a simple solution to the above errors: wait and relaunch the script after some time (hours or days), if software developers repair or synchronize their code with the newly updated libraries (which generally happens eventually), your FlightGear will compile fine as if the previous error never took place.

Sometimes it happens that the script fails to compile only [[Fgrun|FGRun]], [[FGCom]] or atlas, if you then see the run_fgfs.sh file it means that FlightGear installation was successful and you can safely run it.

=== OpenRTI undefined reference errors ===

Sometimes, due to the way <tt>download_and_compile.sh</tt> builds projects, linking errors might occur. This is the case with the error “libRTI-NG.so: undefined reference to xxx”. You might want to patch the <tt>download_and_compile.sh</tt> script to clean OpenRTI with <code>rm -f CMakeCache.txt && rm -rf CMakeFiles/</code>, or just restart the build in a clean environment. Assuming you are in the base directory from which you ran <tt>download_and_compile.sh</tt>, you can run <code>download_and_compile.sh --cleanup</code> (see [[#Cleaning built and installed files|Cleaning built and installed files]]). Alternatively, the following command could be used:
$ rm -rf build/* install/simgear/ install/openrti/ install/flightgear/share/ install/flightgear/bin/

See {{forum link|t=26244|text=this thread}} for more details. Note that <tt>download_and_compile.sh</tt> didn't have the <code>--cleanup</code> option at that time!

== Options ==

=== Release selection ===

* Build the latest stable release: <code>-s</code>
* Build the latest Long Term Stable release: <code>--lts</code>
* Build the previous Long Term Stable release: <code>--old-lts</code>

Long Term Stable (<code>--lts</code>) is supposed to yield a more stable setup than what you would obtain with option <code>-s</code>, however it will generally be older. Both of these options are suitable for users.

If you pass none of <code>-s</code>, <code>--lts</code> and <code>--old-lts</code> in a <tt>download_and_compile.sh</tt> invocation, you'll build the the ''next'' suite, which contains the development version of FlightGear. The corresponding FlightGear code will be very recent but may well be unstable—this is particularly the case starting from July 2020. This is therefore mostly intended for developers.

=== Skipping most prompts ===

For some important things, <tt>download_and_compile.sh</tt> asks for confirmation in order to be sure that you are well informed about what will be done. When you have a good understanding of these informations, you may want to use the <code>--non-interactive</code> option in order to suppress these prompts (technically, this causes the default answer to be automatically used).

=== Cleaning built and installed files ===

Option <code>--cleanup</code> causes <tt>download_and_compile.sh</tt> to remove everything that was built and installed in the directory it is run from. The Git repositories will not be removed, so this is good if you want to restart a compilation from a clean state.

If you use <code>--cleanup</code> without specifying any component, only this removal will be done (nothing will be compiled nor installed). Otherwise, the usual rules concerning components apply.

=== Multicore acceleration ===

Passing option <code>-j x</code> to <tt>download_and_compile.sh</tt> (where ''x'' is the number of your CPU cores you wish to assign to the job) will considerably speed up the compilation steps. Passing <code>-j$(nproc)</code> is a convenient way to automatically use all available cores.

=== Advanced options ===

* Build a release version: <code>-b Release</code>
* Build a version that should run as fast as a release build, yet has debug information that can be used to post backtraces: <code>-b RelWithDebInfo</code> (this is the default)
* Build a full debug version for very complete bug reporting: <code>-b Debug</code>
* Skip download of distro packages (i.e., by default: <tt>apt-get install ...</tt>): <code>-p n</code>
* Skip retrieving of component downloads and updates (which typically use Git or wget): <code>-d n</code>
* Skip the configure step (like running [https://cmake.org/ CMake] or [https://www.gnu.org/software/autoconf/ autoconf]'s <tt>./configure</tt>): <code>-r n</code>
* Skip compilation of programs: <code>-c n</code>
* Build with compositor: <code>--compositor</code>
* Force the use of a particular branch for a given component: <code>--component-branch ''COMPONENT=BRANCH''</code> (e.g., <code>--component-branch OSG=OpenSceneGraph-3.6</code>, <code>--component-branch FGFS=next</code>, etc.—but remember that components FGFS, SIMGEAR and DATA must ''always'' be in sync). See [[#Component-specific settings|Component-specific settings]] for details.
* Override the repository from which a given component is initially fetched: <code>--override-repo ''COMPONENT''=''SITE'':''ADDRESS''</code> (see [[#Component-specific settings|Component-specific settings]]).
* Generate build.ninja files and build using Ninja: <code>-G Ninja</code>
* Run CMake in verbose mode: <code>--verbose</code> (this shows compilation commands)

For example, if you are a developer and wish to quickly recompile and reinstall only your own modifications for FlightGear, you can do this:
$ download_and_compile.sh -j$(nproc) -p n -d n -r n FGFS

Note that this is the same as:
$ download_and_compile.sh -j$(nproc) -pn -dn -rn FGFS

This command will only rebuild modified files and reinstall FlightGear. Note that depending on the kind of changes you made, reconfiguring and thus dropping the <code>-rn</code> option may be necessary, though (this is the case in particular if you added or removed C++ files).

=== ccache ===
[https://ccache.dev/ ccache] is a compiler cache that enormously speeds up subsequent recompilations (compilation times are often divided by a factor 6 or more). Even if <tt>ccache</tt> is installed and in the <tt>PATH</tt>, <tt>download_and_compile.sh</tt> won't use it by default. To use it, you first need to install it, such as via <code>apt install ccache</code>. Then enable it when building with <tt>download_and_compile.sh</tt> by one of the following methods.

For FlightGear 2024.2 or later, you can pass <code>--cmake-arg ALL="-DENABLE_CCACHE=ON"</code> among the <tt>download_and_compile.sh</tt> options (<code>-DENABLE_CCACHE=ON</code> disables precompiled headers which FlightGear 2024.2 or later uses by default; this is a safety measure).

For FlightGear 2024.1 or earlier, you can set the following environment variables when compiling:
export CMAKE_C_COMPILER_LAUNCHER=ccache
export CMAKE_CXX_COMPILER_LAUNCHER=ccache

Alternatively, you can pass this option to <tt>download_and_compile.sh</tt> (all on a single line):
--cmake-args ALL="-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache"

{{Note|<code>--cmake-arg</code> and <code>--cmake-args</code> are both valid, distinct <tt>download_and_compile.sh</tt> options. The former can pass an option to CMake that may contain spaces; the latter can pass several options at once, but none of them may contain spaces because these are used to delimit the options to pass to CMake. Both options can be used several times on the same command line and for the same components anyway.}}

== Optimus technology ==
If your computer has a GPU with Optimus technology, you need a dedicated script in order to make FlightGear run with the powerful GPU.

After having installed required tools (Bumblebee) you just need to run this command line in your FlightGear installation directory (where you executed <tt>download_and_compile.sh</tt>):
$ sed 's|\./fgfs|optirun ./fgfs|' run_fgfs.sh > run_fgfs_optirun.sh && chmod +x run_fgfs_optirun.sh
Now you can run FlightGear with <code>./run_fgfs_optirun.sh</code>.

The same can be done for the [[FlightGear_Launch_Control|FGRun]] launcher:
$ sed 's|\./fgrun|optirun ./fgrun|' run_fgrun.sh > run_fgrun_optirun.sh && chmod +x run_fgrun_optirun.sh

== See also ==

* {{fgmeta source
| path = fg-from-scratch
| text = fg-from-scratch
}};
* [[Fedora Packages and Compiling]];
* [[Superbuild]];
* [http://geoffmclane.com/fg/fgfs-052.htm Another script] for building FlightGear and all its dependencies in an automated fashion. The page seems a bit oldish, though (as of 2019).

== References ==
<references/>

[[Category:Building from source]]

[[fr:Script de compilation sous Linux Debian/Ubuntu]]
[[nl:Compileren met een Script op Linux Debian/Ubuntu]]

TerraSync

2026-02-26T13:47:56Z

Rominet: /* FlightGear 3.0 and later */ Update info on default TS dir location for Windows

<div style="padding-left:20px;">''Not to be confused with [[TerraGear]], a toolset to generate scenery.''</div>

To see the terrain below your [[aircraft]], you have to install the respective [[scenery]]. This can happen by downloading certain bits of scenery before flying as described in the article [[Howto: Install scenery|installing scenery]].

Alternatively, if you have a steady and reasonably fast internet connection, you can use '''TerraSync'''. It is a utility that automatically downloads the newest version of the needed [[FlightGear]] scenery while the simulator is running. TerraSync runs in the background (optionally as a separate process), monitors your position, and downloads (or updates) the latest scenery from the master scenery server "just in time".
For some time now TerraSync has been integrated into the core FlightGear process, so there is no need to deal with TerraSync for the typical user.

The master repository for TerraSync, i.e. the online resource from which TerraSync downloads its files, is synchronized with the [http://scenemodels.flightgear.org/ FlightGear Scenery Database] once a day. So when using TerraSync, you will always have
# the latest [[File Formats#.2A.stg|.stg-files]], which tell FlightGear where to place an object
# the latest '''static''' models for objects. (Static models define unique objects that exist in one place only, such as famous buildings or landmarks.)
# the latest '''shared''' models for objects. (Generic models used more than once in different places, each can represent many different objects, like generic houses or ships)

== Announcements ==
Also as a result from FSweekend, we are going to test some ideas how to distribute osm2city generated scenery with terrasync. As a first step I have just added a folder called Objects_1 containing the osm2city buildings for e005n46 up to e010n48 [http://flightgear.sourceforge.net/scenery/Objects_1/]. People using the fgfs integrated terrasync should not (yet) notice any difference. When using terrasync.py, you should notice download of files in those folders, however they do not (yet) show up in the scenery. We probably throw away some or all files in that directory without prior notice, so please don't rely on them or make backup copies. Torsten <ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35476181/
|title = <nowiki> [Flightgear-devel] ATTN: terrasync changes </nowiki>
|author = <nowiki> Torsten Dreyer </nowiki>
|date = Nov 7th, 2016
|added = Nov 7th, 2016
|script_version = 0.40
}}</ref>

== News ==
Terrasync started out as a standalone rsync-based utility. However, there doesn't appear to be any good/robust multi-platform librsync available for our use. We wanted to embed terrasync right into the core code so we could better coordinate downloading tiles and then loading them immediately into the sim (versus sometimes running into no tiles or partial tiles if an external tool was running rsync.)<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35061363/
|title = <nowiki>Re: [Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>Curtis Olson</nowiki>
|date = May 3rd, 2016
|added = May 4th, 2016
|script_version = 0.31
}}
</ref>

as some of you have probably noticed, some coding is currently happening in the terrasync corner, mostly by James and some parts by Torsten. The main intention is to get rid of the SVN protocol to distribute scenery but use easier to implement protocols. The idea is to use plain HTTP as the access method for files required by terrasync. This should make it much easier for hosts to set up a mirror, probably enables us to use a CDN for load balancing and also makes the client code slim.

The intention is to migrate to a pure HTTP solution for TerraSync (instead of SVN) after 2016.1 is released, since this will give us many more mirroring and hosting options. The cache files are tiny and reflect the current revision of each file in the local copy; they’re analogous to the data a real SVN client stores in its ‘.svn’ directory in the root of the checkout. I expect the pure HTTP solution will need some very similar files to record the HTTP cache stamps of files it downloads - either one file at the root of the tree, or per-directory. (There’s advantages and disadvantages to both).<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/34767003/
|title = <nowiki>Re: [Flightgear-devel] Launcher changes for 3.8</nowiki>
|author = <nowiki>James Turner</nowiki>
|date = Jan 14th, 2016
|added = May 4th, 2016
|script_version = 0.31
}}
</ref>

* supporting the various possible backends inside the code is a headache, so the intention is to support /only/ the HTTP method inside FlightGear directly, aka ‘built-in terrasync’
* one of the major benefits of the HTTP system, is that is uses SHA1 hashes instead of SVN revisions, to identify files, and there is no base (server) URL stored inside the downloaded directories. This means you can prep a terrasync directory with files downloaded by any mechanism you like (DVD, BitTorrent, copying from another machine) and providing the SHA1 hashes match, the files will not be download again. Any files which are out of date will be refreshed, but only those files. This also means switching from SVN -> HTTP does /not/ download everything again.

Switching servers, even within the same FG session, is also possible and again does not result in any re-downloads, unlike the SVN setup where the server URL is part of the repository structure.
* the terrasync /network protocol/ will remain, which means you can write (in a wide ranges of languages, including Python) your own external terrasync engine, using rsync or any other mechanism you like. My hope is this provides a good and maintainable extension point for very advanced users, while the built-in HTTP mechanism will be be simple and robust (thanks to be being hash-based) for 95% of users.<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35064352/
|title = <nowiki>Re: [Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>James Turner</nowiki>
|date = May 4th, 2016
|added = May 4th, 2016
|script_version = 0.31
}}
</ref>

We already have three mirrors of the complete scenery online, one at sourceforge and two at privately owned servers. The sourceforge mirror receives daily updates from the main scenery export from http://scenery.flightgear.org/ and all other mirrors pull their data from the sourceforge server. We decided to drop the previous method of telling the client about it's nearest mirror by querying a web service ( http://scenery.flightgear.org/svn-server) in favour of using a more stable service provider of the internet: the domain name service (DNS) system. The fgfs client will query a fancy resource record (RR) type of NAPTR (network authority pointer, https://en.wikipedia.org/wiki/NAPTR_record) for the dns name terrasync.flightgear.org and analye the entries to find the best terrasync mirror. Those entries are already configured and can be examined here: https://toolbox.googleapps.com/apps/dig/#ANY/terrasync.flightgear.org This technique should enable us to provide different sets of scenery, eventually even for only parts of the world in a much easier fashion that it would have been the case with SVN. It also spares many gigabytes on the scenery mirror as they don't have to keep all the 50,000+ revisions we already carry around. I'll start adding the required code over the next couple of days to have it running hopefully for the 2016.2 release. I'll post a message to this list when I flip the final switch and enable the new terrasync. In the mean time, you might see some build failures on Jenkins or other hickups of the system. I promise to fix those as quick as possible. BTW: If you use terrafs, you already receive your data from the new http mirrors, although not use the DNS service resolver.<ref>{{cite web
|url = http://sourceforge.net/p/flightgear/mailman/message/35057670/
|title = <nowiki>[Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>Torsten Dreyer</nowiki>
|date = May 2nd, 2016
|added = May 2nd, 2016
|script_version = 0.28
}}
</ref>

the http download method will function very much as before where only the changed files (if any) are downloaded. The svn method requires 2x the actual space because of the way svn works under the hood. Git typically requires that you download every version ever created to get the latest copy (there are work arounds if you just want the most recent version.) So the end result for the average user that just wants to download and use the scenery is that the http method will be lighter weight overall. It also simplifies the code inside FlightGear quite a bit and should make the synchroniation more robust. And as mentioned before, it should simplify the task of setting up a scenery mirror for those that wish to do that. As before, power users will have multiple options for updating scenery or mixing and matching from different sources if they choose. <ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35061856/
|title = <nowiki>Re: [Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>Curtis Olson</nowiki>
|date = May 4th, 2016
|added = May 4th, 2016
|script_version = 0.31
}}
</ref>

The technique of the http repository is much simpler than that of the svn repository and it will be pretty simple to create a local mirror or to download chunks of data. With a bit of to-be-developed scripting (python e.g.) there is no need to download existing data again. I don't know how terramaster works but I am sure it is easy to adapt to the new http access method. <ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35062543/
|title = <nowiki>Re: [Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>Torsten Dreyer</nowiki>
|date = May 4th, 2016
|added = May 4th, 2016
|script_version = 0.31
}}
</ref>

The goal is to completely remove SVN and only use the HTTP repository. I'd like to reach that goal better sooner than later as we currently have two single-points of failure for the SVN-service. The first is the http://scenery.flightgear.org/svn-service web service (runs on a private web server) and the second is the one-and-only svn-server available for public access, also hosted on a private server. If either on of those fails, the SVN-terrasync is dead. I have learned the hard way that not having a fallback is a bad idea.<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35062543/
|title = <nowiki>Re: [Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>Torsten Dreyer</nowiki>
|date = May 4th, 2016
|added = May 4th, 2016
|script_version = 0.31
}}
</ref>

Torsten pushed a patch to SimGear and included a bunch of debug messages in the suspicious loop. (They only pop up with <code>--log-level=debug</code> - also add <code>--log-class=terrasync</code> to keep output sane)<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35063277/
|title = <nowiki>Re: [Flightgear-devel] FW: The future of terrasync</nowiki>
|author = <nowiki>Torsten Dreyer</nowiki>
|date = May 4th, 2016
|added = May 4th, 2016
|script_version = 0.31
}}
</ref>

we now have C++ and Python reference examples, both hopefully easy to hack on. BTW, the C++ tool is here: https://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/io/http_repo_sync.cxx Again, enhancements are welcome. <ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35065868/
|title = <nowiki>Re: [Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>James Turner</nowiki>
|date = May 5th, 2016
|added = May 5th, 2016
|script_version = 0.32
}}
</ref>

{{Appendix}}

== terrasync.py ==
First of all, the script is now part of the {{fgmeta-python source | text = fgmeta-python}} repository<ref>{{cite web
|url = https://gitlab.com/flightgear/flightgear/-/merge_requests/340
|title = FlightGear merge request 340
|author = Florent Rougon
|date = November 14th, 2025
}}</ref><ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/59260673/
|title = <nowiki>[Flightgear-devel] terrasync.py moved to fgmeta-python</nowiki>
|author = Florent Rougon
|date = November 17th, 2025
}}</ref> (this was necessary to share .dirindex processing code with other infrastructure tools, in particular for producing the ''base package''). Installation instructions can be found below the list of files, or more directly in {{fgmeta-python source | path = README.md | text = README.md}}.

The script can provide a complete mirror of the scenery data, also known as TerraSync scenery or just TerraScenery.

{{Caution|If you fully run this script for the first time, it will download more than 90 GB of data and more than 1,800,000 files in 40,000 folders to your hard disk. It will run for hours, probably days (depending on your Internet connection). Since someone has to pay for the bandwidth, please don't let it download large amounts of data unless you have a good reason to do so (like, you maintain a public scenery mirror); otherwise, the service could be discontinued. That being said, if you just want to see the script in action, you can run it for a few seconds and stop it with {{key press|Ctrl|C}}.}}

If you already have at least a partial set of scenery data from the FlightGear built-in TerraSync or even a full TerraScenery, existing and up-to-date files will be reused and won't be downloaded a second time.

=== How it works ===

{{Note|The following is not completely up-to-date. In particular, current terrasync.py has a <code>check</code> mode in addition to the default <code>sync</code> mode. Run <code>terrasync.py --help</code> for up-to-date usage information.}}

The HTTP TerraScenery server holds all the well-know files required for scenery, organized in the also well-known directory structure (/Models, /Objects, /Terrain and /Airports) with all their subdirectories. The content of the /Models folder for example is here: http://flightgear.sourceforge.net/scenery/Models/ Each folder contains a (hidden) file called .dirindex (e.g. http://flightgear.sourceforge.net/scenery/Models/.dirindex) that describes the content of that folder by listing its files, subdirectories and checksums of the files and their subdirectories' .dirindex files. The terrasync.py script does the following (simplified):
* a) download the file at the root of the scenery-url (http://flightgear.sourceforge.net/scenery/.dirindex)
* b) walks into any subdirectory listed within the .dirindex
* c) compares the sha1sum of listed files with the local copy and downloads them on mismatch
* d) for listed subdirectories, calls recursively step b)

Even if all scenery files exist on the server, there are initially still approx. 40,000 .dirindex files missing on your drive and downloading will take hours. To speed up the procedure once you have all .dirindex files locally, try running terrasync.py with the <code>--quick</code> option. This will tell terrasync.py to compare the computed sha1sum of every .dirindex file on your disk with that published in the entry in the parent directory's .dirindex. If you have an up-to-date mirror, this will be ''very'' quick as only the root .dirindex needs to be downloaded. Subsequent updates with the <code>--quick</code> option will also be very fast as only the updated files will be downloaded and also the .dirindex files of the parent folders up to the root directory.

So far, we have just added files to your disk, what about files that have been removed on the server? The script usually does not touch them unless you add <code>--remove-orphan</code> to the command-line. By doing so, you ask terrasync.py to remove all files (not directories) that exist in a subdirectory but are not listed in the corresponding .dirindex file.

If you don't want to download everything into your current working directory, add <code>--target=/some/folder</code> to your command line. This describes pretty much everything terrasync.py does. Here are some examples how to use it:

<syntaxhighlight lang="bash">
# fetch everything from the master repository server into /home/joe/fg/scenery, keep orphan files, (re-)download every .dirindex file
terrasync.py --target=/home/joe/fg/scenery

# just pull in changes, quick and lean for subsequent updates
terrasync.py --target=/home/joe/fg/scenery --quick

# run a mirror, only keep those files listed on the server
terrasync.py --target=/home/joe/fg/scenery --quick --remove-orphan

# use another server to pull the data, not the sourceforge master
terrasync.py --target=/home/joe/fg/scenery --url=http://someserver.org/otherscenery

# restrict the area (must be integers, not decimals)
terrasync.py --target=/home/joe/fg/scenery --top 50 --left 18 --bottom 49 --right 19
</syntaxhighlight>

Enjoy, feedback welcome.<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35081518/
|title = <nowiki> [Flightgear-devel] Clone the HTTP scenery data with terrasync.py </nowiki>
|author = <nowiki> Torsten Dreyer </nowiki>
|date = May 11th, 2016
|added = May 11th, 2016
|script_version = 0.40
}}</ref>

== Enabling TerraSync ==

=== FlightGear 3.0 and later ===
As of the FlightGear 3.0 release, TerraSync has changed significantly. By default, when enabled with <code>--enable-terrasync</code><ref name="enabling-TerraSync-with-specific-launchers>In FGRun, this can be done via the appropriate checkbox on the last page. In FFGo, just uncomment the <code>--enable-terrasync</code> option from the default configuration in the Options Window (the “big window” on the left, below the aircraft list).</ref>, TerraSync now downloads to download_dir/TerraSync, where download_dir is FlightGear's download directory.

FlightGear's download directory may be explicitly set using FlightGear's <code>--download-dir</code> [[Command line options|command line option]], otherwise it defaults to:
*[[$FG_HOME]] on non-Windows systems;
* <tt>%USERPROFILE%\FlightGear\Downloads</tt> on Windows (which may be located under <tt>C:\Users\username\Documents</tt>, however there are likely several possibilities depending on the Windows version and configuration).

Optionally, the TerraSync directory may be explicitly set using FlightGear's <code>--terrasync-dir</code> [[Command line options|command line option]], the launcher settings, or through the <tt>Advanced > General</tt> dialog of FGRun. TerraSync will then download to that directory, regardless of FlightGear's download directory. The directory is automatically given top priority, unless specified otherwise in [[$FG_SCENERY]]. No other configuration is needed.

If you neither pass <code>--terrasync-dir</code> nor <code>--download-dir</code> to FlightGear, then the '''default TerraSync directory''' is:
*<tt>[[$FG_HOME]]/TerraSync</tt> on non-Windows systems;
* <tt>%USERPROFILE%\FlightGear\Downloads\TerraSync</tt> on Windows (which is ''possibly'' under <tt>C:\Users\username\Documents</tt> but probably depends on the Windows version and configuration).

=== FlightGear 2.4 up to and including 2.12 ===
As of FlightGear 2.4, TerraSync controls are integrated in the usual FlightGear menu, under <tt>Environment > Scenery Download</tt>. You can also check the "Download scenery on the fly" in the setup GUI. Note that if you set your aircraft to start in a new area, where you have not yet downloaded any scenery, your aircraft may first appear to be in the water until sufficient scenery has downloaded. You can go to <tt>Environment > Scenery Download</tt> and choose "Manual Refresh" to apply scenery updates.

=== POSIX compliant [[command line]] shell ===

Start TerraSync:

<code>% nice terrasync -p 5500 -S -d "$HOME/fgfsScenery"</code>

The -S option tells terrasync to use the SVN protocol to fetch data. If you omit it terrasync will use the rsync program instead (which has to be installed on your system).

Start FlightGear:

<code>% fgfs --atlas=socket,out,1,localhost,5500,udp --fg-scenery="[[$FG_ROOT]]/Scenery/:$HOME/fgfsScenery"</code>

The full documentation and source for TerraSync is located in the FlightGear source distribution (in <code>utils/TerraSync/</code>).

=== [[FGRun]] in FlightGear 2.2.0 ===
# After starting FGRun, make sure you are in the first screen where you can set up directories. One time "Back" from the aircraft selection page. You are now at the "Path" page.
# You can create a list of scenery directories next to "[[$FG_SCENERY|FG_SCENERY]]". Select the line that TerraSync will be using and press the "TerraSync directory" button on the right. A small "T" will appear on the selected line, indicating that this one is set up as TerraSync direcotry.
#* The directories are being loaded from top to bottom, so make sure TerraSync is on top (unless you want to "surpass" terrasync and display scenery from another directory). When two directories contain scenery for the same region, FlightGear will take the scenery from the directory higher in the list.
# Finally, go to the last screen. There you have to activate TerraSync as in the following screenshot. Now TerraSync should work. [[File:TerraSync 2.png|500px]]

''Note: Expect your firewall to block it the first time you run it; just tell the firewall to allow TerraSync to use the port.''

=== [[FGRun]] in FlightGear 1.9.1 ===
# After starting FGRun, make sure you are in the first screen where you can set up directories. One time "Back" from the aircraft selection page. You are now here: [[File:TerraSync 1.png|500px]]
# Select the destination folder for all files downloaded by terrasync. Usually the folder <code>[[$FG_ROOT]]\terrasync</code> already exists and you only have to add it to the list (as in the above example). Insure that it is positioned '''above''' your standard scenery folder (here that is <code>FlightGear191\scenery</code>) and all other directories over which the terrasync folder is supposed to have priority. When two directories contain information for the same region, FlightGear will take the information from the directory higher in the list. On Linux make sure the directory does not only to have a T, but also is the topmost folder.
# For TerraSync to know where to deposit the downloaded files, you have to tell the program which folder is the destination folder. In the above example, it is the 3rd in the list.
# Finally, go to the last screen. There you have to activate TerraSync as in the following screenshot. Now TerraSync should work. [[File:TerraSync 2.png|500px]]

''Note: Expect your firewall to block it the first time you run it; just tell the firewall to allow TerraSync to use the port.''

== Troubleshooting ==

=== Corrupted and unreadable files or directories ===
If you get an error similar to the following in the command line console (black dialog):

Airports/L ... failed:
Can't move 'C:\FlightGear\terrasync\Airports\L\E\.svn\tmp\entries' to 'C:\FlightGear\terrasync\Airports\L\E\.svn\entries': The file or directory is corrupted and unreadable.

and possibly the following popup appears:

[[File:TerraSync Taskbar Error.png]]

==== Solution ====
You can probably fix the error by upgrading to Windows 7 Home Premium Service Pack 1.

=== Locked airport directories ===
You get an error indicating locked airport directories while TerraSync is running.

Working copy 'D:\Program Files\FlightGear 2.4.0\terrasync\Airports\K' locked

While those directories often actually ''are'' updated, the error is annoying.

==== Solution ====
Search the TerraSync directory for files named <tt>lock</tt> and delete them. They are supposed to be removed automatically when a TerraSync update is completed, but sometimes that fails.

=== Failure to remove file ===
You get an error indicating that some files can not be removed.

file remove failed: (./.terrasync_cache) reason: Permission denied

TerraSync cache files can not be deleted. You will see errors in console like above. There is not much to do other then delete the <code>.terrasync_cache</code> files manually and then run FlightGear again.

==== Resolution ====
{{caution|Not recommended. Understand the consequences}}

[http://forum.flightgear.org/viewtopic.php?f=17&t=28957&p=278275#p278275 Forum Post w/ PowerShell command is here]

== Internals ==
The SHA1 hashes are what’s in the .dirindex files, both on the server and in the local tree. We do not synchronise time-stamps with the server copies because it complicates (makes much less efficient) mirroring on the server side. I am fairly confident hash clashes are not an issue, if the Git folks don’t think they are. We explicitly do not rely on any custom or particular HTTP headers, to maximise the chance of ‘just working’ with different HTTP providers and CDN options in the future. The structure of the .dirindex files is text based and hopefully trivial to anyone who cares to look at them; they are generated on the server side by some scripts Torsten wrote. The code uses basically identical logic to Git to avoid recalculating SHA hashes for the entire repository; if any of various stat() fields, most especially sie or mod-time, change, we re-compute the hash for that file on disk. Whenever a file’s hash on disk differs from the what the .dirindex file says it should have, we download the file. That’s pretty much a complete description of the synchronisation model. Hence, it’s safe to copy files into the tree using any tool, or modify then - this will cause the stat() data to change, which will cause the code to recompute the SHA hash, which will trigger a re-download to the server-side copy if the SHA does not match. Note there is no provision to have modified (dirty) files inside the tree; they will always be over-written when next checked. <ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35064470/
|title = <nowiki>Re: [Flightgear-devel] The future of terrasync</nowiki>
|author = <nowiki>James Turner</nowiki>
|date = May 4th, 2016
|added = May 4th, 2016
|script_version = 0.32
}}
</ref>
== Related content ==
* [[Howto: Install scenery]]
* [[TerraMaster]]

== Footnotes ==
<references/>

[[Category:Scenery software]]
[[Category:FlightGear feature]]

[[de:TerraSync]]
[[es:TerraSync]]
[[fr:TerraSync]]
[[nl:Terrasync]]

Aircraft-set.xml

2026-01-09T13:28:08Z

Rominet: /* -set.xml Sections */ check_aircraft.py has been packaged and renamed to fg-check-aircraft

The '''aircraft-set.xml''' file (or rather ''name-of-aircraft''-set.xml) is the top level aircraft configuration file. The aircraft-set.xml file should be in the aircraft's root directory, for example <code>[[$FG_ROOT]]/Aircraft/747-400/747-400-set.xml</code>.

When FlightGear loads an aircraft, the aircraft-set.xml file is the main source of information, about other files to load, such as the 3D model and FDM configuration. It also contains meta data that is important when packaging the aircraft before a release of FlightGear, or when searching for aircraft in the UI (for example, the launcher).

== Overview ==
The aircraft-set.xml file is an XML file which contains many recommended pieces.

* A header with meta-data such as author information and a description
* [[Aircraft rating system|Aircraft ratings]] that can be used to select only the more well developed aircraft (or bad ones if you are looking for aircraft to improve)
* [[Howto:Reassign keyboard bindings|Keyboard bindings]]
* Paths to [[Nasal]] modules
* Paths to configuration files for the [[Flight Dynamics Model|flight dynamics model]] (FDMs), [[Howto:Animate models|3D models and their animations]], [[Autopilot configuration reference|autopilot]], [[Howto:Add sound effects to aircraft|sound]] etc.

FlightGear allows a great deal of flexibility when it comes to how to configure an aircraft.

To help provide a more consistent experience for end users, aircraft developers are encouraged to use [[Release:Aircraft Selection Criteria]] as a guide when preparing an aircraft for inclusion in the [[FGAddon]] aircraft repository, especially if you are hoping for your aircraft to become part of the default distribution, such as the c172p for example.

== The aircraft-set.xml file name ==
The ''name-of-aircraft'' portion of ''name-of-aircraft''-set.xml is the name of the aircraft that is used for example when starting FlightGear from the command line (using the <code>--aircraft=''name-of-aircraft''</code> option). For example, if the file name is

fkdr1-set.xml

Then the command line to start with that aircraft is something like:

fgfs.exe --aircraft=fkdr1

=== Multiple aircraft-set.xml files ===
This naming convention gives you the opportunity to create two (or more) aircraft within the aircraft package root directory. For instance one could create two versions of an aircraft using different FDMs, but sharing many or most other features (and .xml files/models), using the following file names:

fkdr1-yasim-set.xml
fkdr1-uiuc-set.xml

When creating multiple aircraft this way, it's very common to put shared XML data into a -common.xml file which is included by both of the -set.xml files. It's important that your common file does ''not'' end in -set.xml, otherwise some systems will erroneously consider the file as another aircraft. Typically the name might be <code>fkdr1-common-sounds.xml</code> or <code>fokker-shared.xml</code> - but anything is fine so long as it doesn't end in <code>-set.xml</code>

{{note|When defining multiple versions of an aircraft, it's important to use some additional tags to link the aircraft together correctly - this improves the user experience by telling various places which -set.xml is the most important one. See below for the <code><variant-of></code> and <code><primary-set></code> tags.}}

=== Multiplayer aircraft ===
In Flightgear version 2020.3.1 and later, the aircraft-set.xml file is also used when showing [[Howto:Multiplayer|multiplayer]] aircraft, as part of the implementation of [[Changelog 2020.1#Multiplayer|Multiplayer Views]]. For historical reasons multiplayer packets contain only the path to the aircraft model (in essence the string in the <code>/sim/model/path</code> [[Property tree|property]]), not the -set.xml file. Internally Flightgear use a heuristic to find a corresponding -set.xml file.

There is also a feature that will load an AI aircraft model if it shares the same path, in essence from

[[$FG_ROOT]]/'''AI'''/Aircraft/''Aircraft-name''/Models/''Model-and-animation-configuration''.xml

instead of

$FG_ROOT/Aircraft/''Aircraft-name''/Models/''Model-and-animation-configuration''.xml

Note that the AI aircraft model need not be an XML file with a model and animation configuration, but can also be a plain .ac (AC3D) file with a 3D model.

Unfortunately, as this feature have been rather unknown and possibly undocumented for many years, few aircraft developers have provided such a model with their aircraft.

Needless to say, aircraft developers are highly encouraged to provide such a model with the aircraft.

== The property tree ==
{{main article|Property tree}}

The property tree contain a tree-like representation of various key-value pair properties that are used for configuration of and communication between different parts of FlightGear.

Most of the properties can be set using various configuration files and can be manipulated while FlightGear is running. Some of them are manipulated by FlightGear itself, some by the FDM, some by aircraft systems and [[Nasal]] scripts. Properties can also be manipulated manually when FlightGear is running using the [[property browser]].

== -set.xml Sections ==
The aircraft-set.xml file is a [[PropertyList XML files|PropertyList XML file]] that will configure properties in the property tree when an aircraft is loaded. When you view the property tree via the in-sim inspector, the properties you see are those defined in your -set.xml, combined with all the properties defined at runtime by the FDM, instruments, renderer and so on.

Since the -set.xml can grow to become very large, it's common to break it into several pieces. This is especially important when using multiple -set.xml files to avoid code duplication, but it can be very helpful in all cases to keep the main -set.xml file clear and readable. Splitting the file up is done via the PropertyList <code>include</code> syntax.

{{note|Most of these tags are optional.}}

{{note|The [https://pypi.org/project/FlightGear/ <code>flightgear</code> Python package] built from [[FGMeta-Python]] contains a script called <code>fg-check-aircraft</code> that can validate <tt>-set.xml</tt> files and report potential problems. Installation instructions for this package are given in {{fgmeta-python source | path = README.md | text = FGMeta-Python's README.md}}. Then run <code>fg-check-aircraft --help</code> for script usage (basically, you need to specify suitable <code>--include</code> options and tell which directories you want to check).}}

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<sim>
</syntaxhighlight>

XML file header and opening <code><PropertyList></code> and <code><sim></code> tags

==== Name & Description ====

<syntaxhighlight lang="xml">
<description></description>
</syntaxhighlight>

The name that will be shown in the aircraft selection dialog of [[FGRun]] and other GUIs. It's called '''description''' but consider it the human-readable name for the aircraft. It's the primary thing users will see of your aircraft in UIs, so try to make it as informative as possible without being too long. Many authors include the manufacturer in the name, but this is not always necessary: e.e there's no need to call an aircraft 'Mikoyan-Gurevich MiG 27 ML (Flogger)'. In this case 'MiG 27ML' or 'Mikoyan MiG-27ML' is likely fine. Nickname such as the NATO reporting name here are good to include in the longer description (see next next section) since this is also searchable in the UI.

<syntaxhighlight lang="xml">
<long-description>The Cessna 172 is the most popular general aviation aircraft in the world, with
over 40,000 examples built. The aircraft evolved from the earlier Cessna 170, and is available with
a huge range of instruments and engines. This examples features the a Lycoming IO-360 engine
and traditional mechanical flight instruments, typical of a new aircraft from 1986.
</long-description>
</syntaxhighlight>

A brief description of the aircraft, typically a few sentences or paragraphs. Do not including formatting in this text since it will be re-formatted by the UI. (Line breaks to separate paragraphs are ok). Since this text is also searchable, this is a good place to include nick-names or other information (eg, historical manufacturer names) to aid in discovery.

<syntaxhighlight lang="xml">
<aircraft-version></aircraft-version>
</syntaxhighlight>

Version of the aircraft. Often the date of the last change or a version number.


==== Minimum FlightGear version ====

<syntaxhighlight lang="xml">
<minimum-fg-version></minimum-fg-version>
</syntaxhighlight>

This will make FlightGear show a warning dialog stating that the aircraft might not work as expected or at all if the FlightGear version loading it is too old.

This is useful of you know that you are using features not available for older versions of FlightGear.

==== Expected aircraft folder name ====

<syntaxhighlight lang="xml">
<expected-aircraft-dir-name></expected-aircraft-dir-name>
</syntaxhighlight>

This will make FlightGear show a warning dialog if the aircraft do not have the expected folder name, suggesting that the user rename the aircraft to the aircraft name given above.

This is useful if you expect users to download your aircraft from for example GitHub, which will add a hyphen and a branch name to the folder name, most often <code>-master</code>. This will usually break a lot of things, for example showing the blue and yellow "infamous glider" instead of the aircraft model, as FlightGear do not find the aircraft model.

==== Ratings ====

<syntaxhighlight lang="xml">
<rating>
<FDM type="int"></FDM>
<systems type="int"></systems>
<cockpit type="int"></cockpit>
<model type="int"></model>
</rating>
</syntaxhighlight>

The aircraft rating, using the criteria outlined in the article [[Aircraft rating system]], gives a (reasonably) objective rating based on the availability and quality of various aspects of the aircraft.

==== Authors & Maintainers ====

<syntaxhighlight lang="xml">

<author></author>


<authors>
<author n="0">
<name>Wilbur Wirght</name>
<description>FDM, systems</description>
<nick>wwright</nick>
</author>
<author n="1">
<name>Orville Wirght</name>
<description>model and sounds</description>
<email>orville@gmail.com</email>
</author>
</authors>
</syntaxhighlight>

Previously, aircraft could define a single <author> tag with a string listing the authors of the aircraft. This often ended up containing other information, and for complex aircraft, could become very long and unreadable in some places, such as the splash screen.

For FlightGear 2018.3.0 onwards there is a replacement system, based around a structured list of authors. For each author their name can be supplied, and optionally other data if desired: nickname, email and a description of what they contributed. (The strucutre of this XML deliberately matches that used for add-ons)

Both the old and and new data can co-exist to allow aircraft compatability with older versions of FlightGear.

To distinguish contributions and previous authors from active maintainers, there is a seperate maintainers section which can be provided. The syntax is the same as for the authors, but the contact email is more important. In the future this might potentially be used to contact / notify all maintainers of aircraft. (Nickname and description are not used for maintainers)

<syntaxhighlight lang="xml">
<maintainers>
<maintainer n="0">
<name>Wilbur Wirght</name>
<email>ww@wright-brothers.com</email>
</maintainer>
</maintainers >
</syntaxhighlight>

==== Variants ====

When you have multiple -set.xml files in an aircraft directory, one of them should be indicated as the default or primary, and other -set.xmls should be marked as variants of this. This is important so the packaging system knows which -set.xml best describes the whole directory. It's usually quite clear what the main or principle -set.xml should be, but sometimes an arbitrary decision is needed. (For example, with the 777, should the -200 or -300 be the primary aircraft? In practice it doesn't matter)

In the main -set.xml, add the following:

<syntaxhighlight lang="xml">
<primary-set type="bool">true</primary-set>
</syntaxhighlight>

In each variant -set.xml, add the following:

<syntaxhighlight lang="xml">
<variant-of>....mainAircraftName....</variant-of>
</syntaxhighlight>

For example if the main aircraft -set.xml is 'dc3-set.xml', and the variants are 'c47-set.xml' and 'dst-set.xml', you would add:

<syntaxhighlight lang="xml">
<variant-of>dc3</variant-of>
</syntaxhighlight>

in both c47-set.xml and dst-set.xml. This ensures the information from dc3-set.xml will be used when describing the entire package. In this example it's clear the DC-3 should be the primary aircraft because that is the most commonly recognised version - the C-47 and Douglas Sleeper Transport are both useful variants that might exist, but DC-3 is the most generic name / variant.

==== Tags ====

The [[Catalog metadata|tag system]] allows systems to categorise aircraft, for example allowing more advanced searches in the future. Tags allow better feedback to the user when interacting with your aircraft - for
example if the aircraft is tagged as towable, a glider, or a helicopter, the startup behaviour can be customised.

Most importantly, set the following tags if appropriate:

* glider
* helicopter
* floats
* skis
* seaplane
* airship
* amphibious
* vtol

These tags are the most helpful in customising the start-up experience based on the type of aircraft. (Especially, which starting locations are offered / preferred when searching)

<syntaxhighlight lang="xml">
<tags>
<tag n="0">boeing</tag>
<tag n="1">vtol</tag>
<tag n="2">glider</tag>
</tags>
</syntaxhighlight>

==== Urls ====

Beginning with FlightGear 2018.3.0, aircraft can list significant URLs, such as their home page, support forum or code repository. Again the format matches that uses for add-ons:

<syntaxhighlight lang="xml">
<urls>
<home-page>http://wiki.flightgear.org/UFO_from_the_%27White_Project%27_of_the_UNESCO</home-page>
<support>http://forum.flightgear.org</support>
<wikipedia>https://en.wikipedia.org/wiki/Unidentified_flying_object</wikipedia>
<code-repository>https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/Aircraft/ufo/</code-repository>
</urls>
</syntaxhighlight>

The support URL is perhaps the most important, to direct users to a forum or bug-tracker where they can ask questions or report issues with the particular aircraft. Note that while multiple URLs of each type are in theory permitted, at the moment only the first one of each type will be used in the UI. (This may change in the future)

==== Previews ====

The preview system allows UI to show a visual preview of the aircraft during startup, on the website, and in the launcher. Several images can be provided, showing the aircraft exterior and interior. These are also used to provide an improved splash-screen experience, replacing the older system described below. Images should be 1024x768 with no text (as that is added dynamically) and minimal post-processing.

<syntaxhighlight lang="xml">
<previews>
<preview>
<type>exterior</type>
<splash type="bool">true</splash>
<path>Previews/exterior-1.png</path>
</preview>
<preview>
<type>exterior</type>
<splash type="bool">true</splash>
<path>Previews/exterior-f16a-2.png</path>
</preview>
<preview>
<type>panel</type>
<splash type="bool">false</splash>
<path>Previews/cockpit.png</path>
</preview>
</previews>
</syntaxhighlight>

Previews are tagged to allow automatic selection for certain use cases. It's recommended to include at least one exterior, daytime shot of the aircraft, and one interior shot fo the main instrument panel from the pilot's viewpoint. Beyond this any image of the aircraft is acceptable. Avoid including logo, badge or text elements in preview images since this gives poor quality results and restricts how the images can be used - different uses of the images will composite their own elements on top.

Preview file paths are relative to the -set.xml file. Permitted types at present are <code>exterior</code> and <code>panel</code> - the type can also be committed. By default all previews are considered for random selection as the splash screen - to prevent a particular preview being used as the splash screen, set the <code>splash</code> tag to <code>false</code>.

==== Flight-model (FDM) ====

<syntaxhighlight lang="xml">
<flight-model></flight-model>
</syntaxhighlight>

The FDM the aircraft is using. Use <code>yasim</code> for [[YASim]] and <code>jsb</code> for [[JSBSim]].

<syntaxhighlight lang="xml">
<aero></aero>
</syntaxhighlight>

The filename of the FDM file, without <code>.xml</code>. For instance, if your FDM file is sopwithCamel1F1.xml, the aero section would look like <code><nowiki><aero>sopwithCamel1F1</aero></nowiki></code>.

==== Startup ====

The startup section contains information used to show the splash screen for your aircraft. The recommend approach is to use the previews system described above, optionally marking some previews as suitable or unsuitable for use as a splash screen. When using the previews system to provide a splash screen, you can optionally provide a logo image. This replaces the default text (containing the aircraft name) with a presumably partially-transaprent overlay,
allowing more interesting graphics to be displayed on the splash screen.

<syntaxhighlight lang="xml">
<sim>
<startup>
<splash-logo-image>beechcraft-logo.png</splash-logo-image>
</startup>
</sim>
</syntaxhighlight>

When using a logo image, it should be a PNG with an alpha channel enabled, and will be blended over the selected preview image automatically. At present the placement is hard-coded, but this could be extended- if you'd like this added please ask on the developer mailing list.

The legacy splash screen system does not use previews, but instead uses the following syntax:

<syntaxhighlight lang="xml">
<sim>
<startup>
<splash-texture n="0"></splash-texture>
<splash-texture n="1"></splash-texture>
</startup>
</sim>
</syntaxhighlight>

Because old splash screens typically included text and logo elements, the splash screen appearance is different in this case, to ensure all text is legible. (Information added by FlightGear such as version and startup progress, is moved to avoid overlapping, and the scaling behaviour is different)

==== Visual aircraft model ====

<syntaxhighlight lang="xml">
<model>
<path></path>
<fallback-model-index></fallback-model-index>
</model>
</syntaxhighlight>

The file path to either a plain .ac (AC3D) 3D model or a model and animation configuration XML file. This path is also used when loading multiplayer aircraft and needs to be in the long form <code>Aircraft/<aircraft folder>/Models/<model file></code> so FlightGear can find it for multiplayer aircraft. The <code>fallback-model-index</code> is used to set what aircraft model be used to render their aircraft over multiplayer if a user does not have their aircraft installed or if the aircraft is outside the [[Level Of Detail (LOD) Ranges#AI/MP ranges|level of detail range]]. See [[MP Fallback models]] for more details.

<syntaxhighlight lang="xml">
<sound>
<path></path>
</sound>
</syntaxhighlight>

The path to a [[Howto:Add sound effects to aircraft|sound configuration XML file]]. If for example you find a nice WAV file of the jet engine you're using, you can fix it up with your favorite sound editor so it loops nicely and include that into your model (I've noticed a few models where it can get quite annoying when the loop length is so small you can really notice it) so make it smooth.

<syntaxhighlight lang="xml">
<panel>
<path></path>
</panel>
</syntaxhighlight>

File path to the 2D panel configuration XML file. We prefer 3D cockpits, which are linked in the model .xml file.

<syntaxhighlight lang="xml">
<autopilot>
<path></path>
</autopilot>
</syntaxhighlight>

File path to the autopilot configuration XML file. For details, see for example [[Autopilot configuration reference]].

<syntaxhighlight lang="xml">
<checklists include=""/> 
</syntaxhighlight>

Configuration XML file defining a [[Aircraft Checklists|checklist]] (available since version 3.0).

<syntaxhighlight lang="xml">
<variant-of></variant-of>
</syntaxhighlight>

Since 3.6, there is a new <code><variant-of></code> tag that can be added. This is used by the [[Integrated Qt5 Launcher|integrated Qt5 launcher]] to easily select a variant of an aircraft. For example, the [[British Aerospace Sea Harrier|BAe Sea Harrier FA2]] is a variant of the BAe Sea Harrier, and the ''Cessna 172P - Canvas Demo'' is a variant of the [[Cessna 172P]]. Additionally, this could be used for different [[Talk:Aircraft_Checklists#In-air_startups_.26_supporting_Startup_Situations|startup situations]] too.

Example from the {{fgaddon aircraft source|777|777-200ER-set.xml|l=11|text=777-200ER-set.xml}}: <code><variant-of>777-200</variant-of></code>

<syntaxhighlight lang="xml">
</sim>
</syntaxhighlight>

==== Performance and Flight-planning ====

From FlightGear 2018.3.0 onwards, it's possible to include additional data to improve user feedback and flight-plan creation. Note this information lives under the top-level <code>aircraft</code> tag, and '''not''' under <code>sim</code> as all the content above does.

<syntaxhighlight lang="xml">
<aircraft>
<icao>
<wake-turbulence-category>M</wake-turbulence-category> 
<type type="string">B738</type> 

<equipment type="string">SDFGY</equipment>

<surveillance type="string">S</surveillance> 
</icao>
</aircraft>
</syntaxhighlight>

This information is useful in pre-filling an ICAO standard flight-plan based on the aircraft and equipment. In the future it may be reported automatically to ATC clients / networks. To find out the officially registered ICAO type string for an aircraft, ICAO provides [http://www.icao.int/publications/DOC8643/Pages/Search.aspx a lookup service]

<syntaxhighlight lang="xml">
<aircraft>
<performance>
<minimum>
<takeoff-length-ft type="int">6000</takeoff-length-ft>
<landing-length-ft type="int">4000</landing-length-ft>
</minimum>
<climb>

</climb>
<cruise>
<airspeed-knots type="int">400</airspeed-knots>

<altitude-ft type="int">4500</altitude-ft>

</cruise>
<descent>

</descent>
<approach>
<airspeed-knots type="int">120</airspeed-knots>
</approach>
<maximum>
<altitude-ft type="int">21000</altitude-ft> 
<mach type="double">0.875</mach>
<airspeed-knots type="int">180</airspeed-knots> 
</maximum>
</performance >
</aircraft>
</syntaxhighlight>

Performance data is optional, and advisory : it does not influence the system or FDM simulation in any way. Its purpose is to inform flight-planning and user experience, especially to provide reasonable default values when the user selects starting on approach or in the air. The cruise information is valuable in generating a plausible route between two airports (for example, if Victor or Jet airways should be used), and making a crude estimate of the time enroute based on typical cruising speeds.

The minimum runway length information is helpful in preferring certain airfields when searching locations - for example when using the 777 there is little point in considering a 600ft grass strip.

Information on aircraft maximums is valuable in the UI to give feedback when the user requests values which exceed aircraft capabilities: for example starting the C172 at 50000ft altitude or 800kts. (Since we're dealing with a flight-simulation situation, we still permit such uses, but it's beneficial to be able to warn the user they are doing something which will likely not work well)

At present climb and descent information is not included, but future version of FlightGear might support this, to plan realistic climb and descent profiles for the aircraft.

== Related content ==
* [[Aircraft Generation Wizard]] (stalled as of 12/2013)
* [[Aircraft rating system]]
* [[Catalog metadata]]
* [[Howto:3D Aircraft Models]]
* [[Howto:Add sound effects to aircraft]]
* [[Howto:Animate models]]
* [[MP Fallback models]]

[[Category:Aircraft enhancement]]

Howto:Translate FlightGear

2026-01-09T09:00:12Z

Rominet: /* How to translate */ More complement

FlightGear supports localization, that is, showing the user interface in the user's native language rather than in English.

This page will help you translate FlightGear to a new language or improve the existing translations.

== What can be translated ==
The following parts of the simulator can be translated:
* the menus, splash screens, startup tips and the text shown when the <code>--help</code> command-line option is used (FlightGear 2.7.0 and later)
* the shortcut file on Linux systems (FlightGear 2017.1 and later)
* the man pages (FlightGear 2017.3 and later)
* the built-in launcher (FlightGear 2018.3 and later)

== How to translate ==
# Determine the two letter ISO 639-1 language code for the language you want to translate FlightGear to. A list can be found on the [https://www.loc.gov/standards/iso639-2/php/code_list.php Library of Congress Web site].
# Check whether your language already has a subdirectory below [https://gitlab.com/flightgear/fgdata/-/tree/next/Translations?ref_type=heads the Translations directory]. If it does not, ask on the development mailing for the empty translation files to be created for you. (It's better to do this than to copy an existing translation, as this will avoid you accidentally including unwanted data; besides, rules for plural forms must be added {{fgmeta-python source| path = src/flightgear/meta/i18n/__init__.py | text = in FGMeta-Python}} and {{flightgear source| path = src/Translations/LanguageInfo.cxx | text = in FlightGear}}).
# Open the .XLF files in the subdirectory of your language and translate the English strings in them. You can edit the .XLF files in a text editor (such as Notepad++ or GEdit) but you can also use translation tools such as Qt Linguist or any XLIFF editor. Using a structured tool is recommended because it can track the translation state (flagging untranslated strings) and most tools include helpers to partially automate the translation process.
# Start FlightGear to test your translation (for the -Qt.xlf file, you won't see any change unless you rebuild FlightGear with the file in the expected place). By default, the simulator will select the locale of your operating system as the language to use; you can explicitly select a language using the command-line option <code>--language=language code</code> (alternatively, on Unix-like systems, you can set the <code>LANG</code> environment variable as in <code>LANG=fr_FR.UTF-8 fgfs ...</code>).
# Submit your updated .XLF files for inclusion via the development mailing list or a GitLab merge request.

There are two XLF files in each language subdirectory : FlightGear-nonQt.xlf is for the core simulator strings (startup messages, in-sim menus, command line options help, tips, weather scenarios...), and FlightGear-Qt.xlf is for the built-in launcher.

Note that the user interface might have not full Unicode support (some special/accented characters might not be shown): should you encounter such a location, please write to the flightgear-devel mailing list at {{Mailing list e-mail address|flightgear-devel}}.

== How to translate the shortcut file ==
Open [{{flightgear url|path=package/org.flightgear.FlightGear.desktop}} the FlightGear <code>.desktop</code> file] and translate the ''GenericName'', ''Comment'' and ''Keywords'' keys (add the ''GenericName[xx]'', ''Comment[xx]'' and ''Keywords[xx]'' keys, where ''xx'' is the two letter ISO 639-1 code of the language).

== How to translate the man pages ==
# Determine the two letter ISO 639-1 language code for the language you want to translate the man pages to.
# Check whether your language already has a subdirectory below [{{flightgear url|path=man}} the man pages directory]. If it does not, create an empty directory in it named after the language code, then copy <code>man1</code> and <code>man5</code> from the man pages directory to the directory of your language.
# Edit [{{flightgear url|path=man/CMakeLists.txt}} man/CMakeLists.txt] and add the instruction <code>add_subdirectory(xx)</code> in the <code>if(NOT WIN32)</code> block (where ''xx'' is the language code).
# Edit <code>man/xx/man1/CMakeLists.txt</code> and <code>man/xx/man5/CMakeLists.txt</code>: on the last row, set the installation directory (<code>DESTINATION</code>), respectively, to <code>${CMAKE_INSTALL_MANDIR}/xx/man1</code> and <code>${CMAKE_INSTALL_MANDIR}/xx/man5</code>.
# Open the man pages in the subdirectory of your language and translate them.

== Using QtLinguist to translate XLF Files ==

One can use QtLinguist (application from the QT package) to translate XLIFF files. Install QT package from the Qt home page (https://www.qt.io/download). Opening QtLinguist will show default translation environment. Open XLF file and start translating. The interface is divided into four main sections:

* Context - this is a grouping of the strings to translate. Defined by the developer. Icon beside the group show translation status. Everything should be in the end with the green check sign.
* Strings - strings in the selected group. Select string to translate it
* Sources and Forms - additional information about location of the translated string in the source code (not always visible and with correct information)
* Source text - the main place where translation occurs. Translate here selected strings.

One have to translate the original strings into the target language. Icon beside the original text in the 'Strings' section will show status. Green check mark when everything is correct. Yellow question mark, when the translation is in place but it it not marked as "verified". Untranslated strings are marked with the grey question mark. Sometimes QtLinguist displays exclamation mark - this shows that the translated text does not conform to the original text e.g. original text ends with the punctuation but the translated text not. Buttons (and keyboard shortcuts) on the main toolbar area helps with the strings matching. When the text is translated and you're comfortable with the style/meaning etc. you select green check mark button. It marks the translation as translated-verified. So this is the expected end state for this.

[[File:Qt Linquist.png|700px|frameless]]

Reference:
* [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist manual]
* [https://doc.qt.io/qt-5/linguist-translators.html Qt Linguist for translators guide]

== Related content ==
* [[Howto: Translate FlightGear Launch Control‎‎]]
* [[Translation requests]]

[[Category:Howto|Translate FlightGear]]

Howto:Translate FlightGear

2026-01-09T08:45:14Z

Rominet: /* How to translate */ Little complements

FlightGear supports localization, that is, showing the user interface in the user's native language rather than in English.

This page will help you translate FlightGear to a new language or improve the existing translations.

== What can be translated ==
The following parts of the simulator can be translated:
* the menus, splash screens, startup tips and the text shown when the <code>--help</code> command-line option is used (FlightGear 2.7.0 and later)
* the shortcut file on Linux systems (FlightGear 2017.1 and later)
* the man pages (FlightGear 2017.3 and later)
* the built-in launcher (FlightGear 2018.3 and later)

== How to translate ==
# Determine the two letter ISO 639-1 language code for the language you want to translate FlightGear to. A list can be found on the [https://www.loc.gov/standards/iso639-2/php/code_list.php Library of Congress Web site].
# Check whether your language already has a subdirectory below [https://gitlab.com/flightgear/fgdata/-/tree/next/Translations?ref_type=heads the Translations directory]. If it does not, ask on the development mailing for the empty translation files to be created for you. (It's better to do this than to copy an existing translation, as this will avoid you accidentally including unwanted data; besides, rules for plural forms must be added {{fgmeta-python source| path = src/flightgear/meta/i18n/__init__.py | text = in FGMeta-Python}} and {{flightgear source| path = src/Translations/LanguageInfo.cxx | text = in FlightGear}}).
# Open the .XLF files in the subdirectory of your language and translate the English strings in them. You can edit the .XLF files in a text editor (such as Notepad++ or GEdit) but you can also use translation tools such as Qt Linguist or any XLIFF editor. Using a structured tool is recommended because it can track the translation state (flagging untranslated strings) and most tools include helpers to partially automate the translation process.
# Start FlightGear to test your translation (for the -Qt.xlf file, you won't see any change unless you rebuild FlightGear with the file in the expected place). By default, the simulator will select the locale of your operating system as the language to use; you can explicitly select a language using the command-line option <code>--language=language code</code> (alternatively, on Unix-like systems, you can set the <code>LANG</code> environment variable as in <code>LANG=fr_FR.UTF-8 fgfs ...</code>).
# Submit your updated .XLF files for inclusion via the development mailing list or a GitLab merge request.

There are two XLF files in each language subdirectory : one for the core simulator strings (startup messages, command line arg help, hints) and one for the launcher.

Note that the user interface might have not full Unicode support (some special/accented characters might not be shown): should you encounter such a location, please write to the flightgear-devel mailing list at {{Mailing list e-mail address|flightgear-devel}}.

== How to translate the shortcut file ==
Open [{{flightgear url|path=package/org.flightgear.FlightGear.desktop}} the FlightGear <code>.desktop</code> file] and translate the ''GenericName'', ''Comment'' and ''Keywords'' keys (add the ''GenericName[xx]'', ''Comment[xx]'' and ''Keywords[xx]'' keys, where ''xx'' is the two letter ISO 639-1 code of the language).

== How to translate the man pages ==
# Determine the two letter ISO 639-1 language code for the language you want to translate the man pages to.
# Check whether your language already has a subdirectory below [{{flightgear url|path=man}} the man pages directory]. If it does not, create an empty directory in it named after the language code, then copy <code>man1</code> and <code>man5</code> from the man pages directory to the directory of your language.
# Edit [{{flightgear url|path=man/CMakeLists.txt}} man/CMakeLists.txt] and add the instruction <code>add_subdirectory(xx)</code> in the <code>if(NOT WIN32)</code> block (where ''xx'' is the language code).
# Edit <code>man/xx/man1/CMakeLists.txt</code> and <code>man/xx/man5/CMakeLists.txt</code>: on the last row, set the installation directory (<code>DESTINATION</code>), respectively, to <code>${CMAKE_INSTALL_MANDIR}/xx/man1</code> and <code>${CMAKE_INSTALL_MANDIR}/xx/man5</code>.
# Open the man pages in the subdirectory of your language and translate them.

== Using QtLinguist to translate XLF Files ==

One can use QtLinguist (application from the QT package) to translate XLIFF files. Install QT package from the Qt home page (https://www.qt.io/download). Opening QtLinguist will show default translation environment. Open XLF file and start translating. The interface is divided into four main sections:

* Context - this is a grouping of the strings to translate. Defined by the developer. Icon beside the group show translation status. Everything should be in the end with the green check sign.
* Strings - strings in the selected group. Select string to translate it
* Sources and Forms - additional information about location of the translated string in the source code (not always visible and with correct information)
* Source text - the main place where translation occurs. Translate here selected strings.

One have to translate the original strings into the target language. Icon beside the original text in the 'Strings' section will show status. Green check mark when everything is correct. Yellow question mark, when the translation is in place but it it not marked as "verified". Untranslated strings are marked with the grey question mark. Sometimes QtLinguist displays exclamation mark - this shows that the translated text does not conform to the original text e.g. original text ends with the punctuation but the translated text not. Buttons (and keyboard shortcuts) on the main toolbar area helps with the strings matching. When the text is translated and you're comfortable with the style/meaning etc. you select green check mark button. It marks the translation as translated-verified. So this is the expected end state for this.

[[File:Qt Linquist.png|700px|frameless]]

Reference:
* [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist manual]
* [https://doc.qt.io/qt-5/linguist-translators.html Qt Linguist for translators guide]

== Related content ==
* [[Howto: Translate FlightGear Launch Control‎‎]]
* [[Translation requests]]

[[Category:Howto|Translate FlightGear]]

Howto:Translate FlightGear

2026-01-09T08:29:11Z

Rominet: /* How to translate */ Add other reasons for asking on the ML when a new language is to be added

FlightGear supports localization, that is, showing the user interface in the user's native language rather than in English.

This page will help you translate FlightGear to a new language or improve the existing translations.

== What can be translated ==
The following parts of the simulator can be translated:
* the menus, splash screens, startup tips and the text shown when the <code>--help</code> command-line option is used (FlightGear 2.7.0 and later)
* the shortcut file on Linux systems (FlightGear 2017.1 and later)
* the man pages (FlightGear 2017.3 and later)
* the built-in launcher (FlightGear 2018.3 and later)

== How to translate ==
# Determine the two letter ISO 639-1 language code for the language you want to translate FlightGear to. A list can be found on the [https://www.loc.gov/standards/iso639-2/php/code_list.php Library of Congress Web site].
# Check whether your language already has a subdirectory below [https://gitlab.com/flightgear/fgdata/-/tree/next/Translations?ref_type=heads the Translations directory]. If it does not, ask on the development mailing for the empty translation files to be created for you. (It's better to do this than to copy an existing translation, as this will avoid you accidentally including unwanted data; besides, rules for plural forms must be added {{fgmeta-python source| path = src/flightgear/meta/i18n/__init__.py | text = in FGMeta-Python}} and {{flightgear source| path = src/Translations/LanguageInfo.cxx | text = in FlightGear}}).
# Open the .XLF files in the subdirectory of your language and translate the English strings in them. You can edit the .XLF files in a text editor (such as Notepad++ or GEdit) but you can also use translation tools such as Qt Linguist or any XLIFF editor. Using a structured tool is recommended because it can track the translation state (flagging untranslated strings) and most tools include helpers to partially automate the translation process.
# Start FlightGear to test your translation. By default, the simulator will select the locale of your operating system as the language to use; you can explicitly select a language using the command-line option <code>--language=language code</code>.
# Submit your updated .XLF files for inclusion via the development mailing list or a GitLab merge request

There are two XLF files in each language subdirectory : one for the core simulator strings (startup messages, command line arg help, hints) and one for the launcher.

Note that the user interface might have not full Unicode support (some special/accented characters might not be shown): should you encounter such a location, please write to the flightgear-devel mailing list at {{Mailing list e-mail address|flightgear-devel}}.

== How to translate the shortcut file ==
Open [{{flightgear url|path=package/org.flightgear.FlightGear.desktop}} the FlightGear <code>.desktop</code> file] and translate the ''GenericName'', ''Comment'' and ''Keywords'' keys (add the ''GenericName[xx]'', ''Comment[xx]'' and ''Keywords[xx]'' keys, where ''xx'' is the two letter ISO 639-1 code of the language).

== How to translate the man pages ==
# Determine the two letter ISO 639-1 language code for the language you want to translate the man pages to.
# Check whether your language already has a subdirectory below [{{flightgear url|path=man}} the man pages directory]. If it does not, create an empty directory in it named after the language code, then copy <code>man1</code> and <code>man5</code> from the man pages directory to the directory of your language.
# Edit [{{flightgear url|path=man/CMakeLists.txt}} man/CMakeLists.txt] and add the instruction <code>add_subdirectory(xx)</code> in the <code>if(NOT WIN32)</code> block (where ''xx'' is the language code).
# Edit <code>man/xx/man1/CMakeLists.txt</code> and <code>man/xx/man5/CMakeLists.txt</code>: on the last row, set the installation directory (<code>DESTINATION</code>), respectively, to <code>${CMAKE_INSTALL_MANDIR}/xx/man1</code> and <code>${CMAKE_INSTALL_MANDIR}/xx/man5</code>.
# Open the man pages in the subdirectory of your language and translate them.

== Using QtLinguist to translate XLF Files ==

One can use QtLinguist (application from the QT package) to translate XLIFF files. Install QT package from the Qt home page (https://www.qt.io/download). Opening QtLinguist will show default translation environment. Open XLF file and start translating. The interface is divided into four main sections:

* Context - this is a grouping of the strings to translate. Defined by the developer. Icon beside the group show translation status. Everything should be in the end with the green check sign.
* Strings - strings in the selected group. Select string to translate it
* Sources and Forms - additional information about location of the translated string in the source code (not always visible and with correct information)
* Source text - the main place where translation occurs. Translate here selected strings.

One have to translate the original strings into the target language. Icon beside the original text in the 'Strings' section will show status. Green check mark when everything is correct. Yellow question mark, when the translation is in place but it it not marked as "verified". Untranslated strings are marked with the grey question mark. Sometimes QtLinguist displays exclamation mark - this shows that the translated text does not conform to the original text e.g. original text ends with the punctuation but the translated text not. Buttons (and keyboard shortcuts) on the main toolbar area helps with the strings matching. When the text is translated and you're comfortable with the style/meaning etc. you select green check mark button. It marks the translation as translated-verified. So this is the expected end state for this.

[[File:Qt Linquist.png|700px|frameless]]

Reference:
* [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist manual]
* [https://doc.qt.io/qt-5/linguist-translators.html Qt Linguist for translators guide]

== Related content ==
* [[Howto: Translate FlightGear Launch Control‎‎]]
* [[Translation requests]]

[[Category:Howto|Translate FlightGear]]

Howto:Translate FlightGear

2026-01-08T21:52:11Z

Rominet: /* How to translate */ GitLab rather than SourceForge nowadays

FlightGear supports localization, that is, showing the user interface in the user's native language rather than in English.

This page will help you translate FlightGear to a new language or improve the existing translations.

== What can be translated ==
The following parts of the simulator can be translated:
* the menus, splash screens, startup tips and the text shown when the <code>--help</code> command-line option is used (FlightGear 2.7.0 and later)
* the shortcut file on Linux systems (FlightGear 2017.1 and later)
* the man pages (FlightGear 2017.3 and later)
* the built-in launcher (FlightGear 2018.3 and later)

== How to translate ==
# Determine the two letter ISO 639-1 language code for the language you want to translate FlightGear to. A list can be found on the [https://www.loc.gov/standards/iso639-2/php/code_list.php Library of Congress Web site].
# Check whether your language already has a subdirectory below [https://gitlab.com/flightgear/fgdata/-/tree/next/Translations?ref_type=heads the Translations directory]. If it does not, ask on the development mailing for the empty translation files to be created for you. (It's better to do this than copying an existing translation, because of data that will be accidentally included otherwise)
# Open the .XLF files in the subdirectory of your language and translate the English strings in them. You can edit the .XLF files in a text editor (such as Notepad++ or GEdit) but you can also use translation tools such as Qt Linguist or any XLIFF editor. Using a structured tool is recommended because it can track the translation state (flagging untranslated strings) and most tools include helpers to partially automate the translation process.
# Start FlightGear to test your translation. By default, the simulator will select the locale of your operating system as the language to use; you can explicitly select a language using the command-line option <code>--language=language code</code>.
# Submit your updated .XLF files for inclusion via the development mailing list or a GitLab merge request

There are two XLF files in each language subdirectory : one for the core simulator strings (startup messages, command line arg help, hints) and one for the launcher.

Note that the user interface might have not full Unicode support (some special/accented characters might not be shown): should you encounter such a location, please write to the flightgear-devel mailing list at {{Mailing list e-mail address|flightgear-devel}}.

== How to translate the shortcut file ==
Open [{{flightgear url|path=package/org.flightgear.FlightGear.desktop}} the FlightGear <code>.desktop</code> file] and translate the ''GenericName'', ''Comment'' and ''Keywords'' keys (add the ''GenericName[xx]'', ''Comment[xx]'' and ''Keywords[xx]'' keys, where ''xx'' is the two letter ISO 639-1 code of the language).

== How to translate the man pages ==
# Determine the two letter ISO 639-1 language code for the language you want to translate the man pages to.
# Check whether your language already has a subdirectory below [{{flightgear url|path=man}} the man pages directory]. If it does not, create an empty directory in it named after the language code, then copy <code>man1</code> and <code>man5</code> from the man pages directory to the directory of your language.
# Edit [{{flightgear url|path=man/CMakeLists.txt}} man/CMakeLists.txt] and add the instruction <code>add_subdirectory(xx)</code> in the <code>if(NOT WIN32)</code> block (where ''xx'' is the language code).
# Edit <code>man/xx/man1/CMakeLists.txt</code> and <code>man/xx/man5/CMakeLists.txt</code>: on the last row, set the installation directory (<code>DESTINATION</code>), respectively, to <code>${CMAKE_INSTALL_MANDIR}/xx/man1</code> and <code>${CMAKE_INSTALL_MANDIR}/xx/man5</code>.
# Open the man pages in the subdirectory of your language and translate them.

== Using QtLinguist to translate XLF Files ==

One can use QtLinguist (application from the QT package) to translate XLIFF files. Install QT package from the Qt home page (https://www.qt.io/download). Opening QtLinguist will show default translation environment. Open XLF file and start translating. The interface is divided into four main sections:

* Context - this is a grouping of the strings to translate. Defined by the developer. Icon beside the group show translation status. Everything should be in the end with the green check sign.
* Strings - strings in the selected group. Select string to translate it
* Sources and Forms - additional information about location of the translated string in the source code (not always visible and with correct information)
* Source text - the main place where translation occurs. Translate here selected strings.

One have to translate the original strings into the target language. Icon beside the original text in the 'Strings' section will show status. Green check mark when everything is correct. Yellow question mark, when the translation is in place but it it not marked as "verified". Untranslated strings are marked with the grey question mark. Sometimes QtLinguist displays exclamation mark - this shows that the translated text does not conform to the original text e.g. original text ends with the punctuation but the translated text not. Buttons (and keyboard shortcuts) on the main toolbar area helps with the strings matching. When the text is translated and you're comfortable with the style/meaning etc. you select green check mark button. It marks the translation as translated-verified. So this is the expected end state for this.

[[File:Qt Linquist.png|700px|frameless]]

Reference:
* [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist manual]
* [https://doc.qt.io/qt-5/linguist-translators.html Qt Linguist for translators guide]

== Related content ==
* [[Howto: Translate FlightGear Launch Control‎‎]]
* [[Translation requests]]

[[Category:Howto|Translate FlightGear]]

FGAddon

2026-01-08T13:36:43Z

Rominet: /* Command line */ Update releases to something more current

[[File:FGAddon logo.png|270px|right]]

The official '''FGAddon''' [[aircraft]] hangar is a version control repository, hosted on [[FlightGear|FlightGear's]] [[SourceForge]] infrastructure, and used for the day-to-day development of FlightGear aircraft. FGAddon is an {{wikipedia|Apache Subversion}} version control repository. These are aircraft that are not part of the base package (the aircraft that are included in the base package — the [[Cessna 172P]] and the [[UFO]] — are kept in the [[FGData]] repository), but are tagged with each stable release.

The FGAddon aircraft development repository should be considered unstable. When using a stable FlightGear release, it is best to obtain aircraft directly in the launcher. However, as stable releases from FlightGear version 3.4 onwards are tagged and present within the FGAddon repository, the Subversion tools can be a convenient way to obtain individual aircraft or the entire official hangar of approximately 500 aircraft. Also, if using the [[FlightGear build server|lastest nightly releases]] or a [[Building FlightGear|self-compiled version of FlightGear]] from FlightGear's [https://gitlab.com/flightgear Git version control repositories], using FGAddon allows the aircraft to be updated to the latest development versions.

== History ==
[[File:Image103.gif|thumb|Original Win95 icon]]

The FlightGear project was conceived on April 8, 1996 by David Murr who proposed a new flight simulator to be developed by volunteers<ref>David Murr (Apr 9, 1996). FlightGear proposal 1.0: [https://groups.google.com/forum/#!msg/rec.aviation.simulators/ny8HFBE5_T8/OdtIiGNGJc8J "A PROPOSAL FOR A NEW FLIGHT SIMULATOR - home built!@"]. Published on the rec.aviation.simulators newsgroup.</ref><ref>David Murr (1996). FlightGear proposal 2.0: [http://www.flightgear.org/proposal-2.0 FLIGHT GEAR "This truly is as real as it gets!" - a proposal for a new flight simulator - REVISION 2.0].</ref><ref>David Murr (Oct 29, 1996). FlightGear proposal 3.0: [http://www.flightgear.org/proposal-3.0 FLIGHT GEAR FLIGHT SIMULATOR, revision 3.0 - Wednesday, 10.30.96, "The future of flight simulation is here"]. Published on the [http://ftp.igh.cnrs.fr/pub/flightgear/www/old-stuff/flight-gear.9610 flight-gear@infoplane.com mailing list].</ref><ref>David Murr (Sep 11, 1998). FlightGear proposal 3.0.1: [http://www.flightgear.org/proposal-3.0.1 FLIGHT GEAR FLIGHT SIMULATOR, revision 3.0.1 - Friday, Sep.11.98, "The future of flight simulation is here"].</ref>. Part of the initial goals were to develop 2D and 3D graphics routines for the simulator. However this was a huge task that came to an unfinished halt at the start of 1997 as the main developer, Eric Korpela, was finishing his thesis. Therefore starting on May 16, 1997, Curtis Olson relaunched development with a new project based on the OpenGL libraries, allowing a functional flight simulator to be put together in a short period of time<ref>Curtis Olson (Sep 28, 2015). [http://forum.flightgear.org/viewtopic.php?f=42&t=27558&p=259048#p259021 Re: A PROPOSAL FOR A NEW FLIGHT SIMULATOR - home built!@]. Published on the FlightGear forum.</ref>. The first commits were to the original [[FlightGear CVS|flightgear and simgear CVS version control repositories]].

As the project grew, so did the size, quantity, and quality of the FlightGear assets. These assets were not organised and were scattered across different parts of the internet. Therefore it was decided that much of this FlightGear content would be assembled and stored together in a new centralised CVS repository called fgdata, which was created on October 22, 2000. To allow for the legal redistribution of these assets as part of the FlightGear distribution, a GPLv2 only policy was adopted.

In May 2010, development was interrupted by the infamous ''"coffee incident"'' which resulted in the loss of Curtis' home server hosting all of the FlightGear repositories<ref>James Turner (May 20, 2010). [http://thread.gmane.org/gmane.games.flightgear.devel/60340/focus=60341 <nowiki>[Flightgear-devel]</nowiki> Re: Flightgear git repositories (was Re: GIT or CVS - Confusion)] Published on the flightgear-devel mailing list.</ref>. These events resulted in a [[FlightGear CVS|mass migration of all the CVS repositories to Git repositories]]. Due to bandwidth issues, it was decided that the new repositories would be hosted on the Gitorious open source infrastructure.

With time as the project grew, the size and scope of the fgdata repository mushroomed, mainly due to the growing number of aircraft stored in [[$FG_ROOT]]/Aircraft, so that a split was inevitable. A first splitting attempt was organised by Gijs de Rooy and announced on October 18, 2011<ref>Cedric Sodhi (Oct 18, 2011) [http://thread.gmane.org/gmane.games.flightgear.devel/66846 <nowiki>[Flightgear-devel]</nowiki> FGData Split Completed - a.k.a Life after the Split] Published on the flightgear-devel mailing list.</ref>. Each aircraft was placed in its own Git repository and all aircraft linked back to fgdata using a Git submodule approach. However this attempt failed and was abandoned. From this date until the end of 2014, the design of the fgdata split was discussed on the development mailing list and summarised in the [[FlightGear Git: splitting fgdata]] wiki article. In the planning stages, the repositories were known as fgdata-old splitting into [[FGData]] (a.k.a. fgdata-new) and FGAddon (a.k.a. flightgear-aircraft and fgaircraft). After half a decade of planning, it was decided that the best solution for FlightGear aircraft development would be a single centralized Subversion repository. This would facilitate community management and maintenance of the aircraft while at the same time providing modularity and smaller downloads and smaller local repository sizes.

In late 2014, Gitorious, the provider of the open source infrastructure for the FlightGear source code and data repositories announced that it would shut its services down by May 2015 due to its acquisition by GitLab. This catalysed the split of fgdata-old and a switch to the SourceForge open source infrastructure for the hosting of the VC repositories. Other parts of the FlightGear infrastructure were already hosted by SourceForge, making the move a natural one. Sealing the deal, SourceForge agreed in writing to host the huge FlightGear aircraft collection, the size of which is unrivaled in open source circles. Today, the FGAddon SVN repository is hosted on SourceForge.

In August 2015, a new FlightGear policy document was written to codify the unwritten standards of the project<ref>[http://www.flightgear.org/flightgear-policy-document/ FlightGear Policy Document and Roadmap], draft document.</ref>. With this document, the licensing policy for the FlightGear aircraft hosted on FGAddon has been updated from being GPLv2-only to now being GPLv2+. To combat licence proliferation, avoid complications using work from one aircraft in another, and for the integrity and good of the FlightGear project, it is strongly recommended that all original content (whether hosted in FGAddon or elsewhere) be GPLv2+ licensed.



== Obtaining aircraft ==

{{tip|If you are interested in obtaining aircraft for stable FlightGear releases and you are unaware of what version control is, you should visit the [[FlightGear_hangars|FlightGear hangars]] for downloading aircraft.}}
{{caution|If the FlightGear and FGAddon aircraft versions do not match, strange bugs should be expected and the version-mismatch combination will not be supported by the FlightGear community.}}

With access to the Subversion (SVN) tools, the FGAddon version control repository can be a convenient way for obtaining aircraft for using within a specific FlightGear version directly from the official source. When using the [[FlightGear Build Server|nightly builds]] or a [[Building FlightGear|version controlled copy of FlightGear]], the most up to date in-development versions of the aircraft should be used so the versions match. The following describes how to use the official repository to obtain aircraft from the perspective of a FlightGear user.

=== Preparation ===
To use the FGAddon repository, the Subversion tools need to be installed:
* '''MS Windows''': Install one of the [https://subversion.apache.org/packages.html#windows many Subversion clients]. For example [https://sliksvn.com/download/ SlikSVN] is one of the best command line versions and the best for aircraft development, and [http://tortoisesvn.net/ TortoiseSVN] provides a user friendly graphical user interface (GUI) by integrating into Windows Explorer.
* '''Mac OS X''': Install the [https://subversion.apache.org/packages.html#osx official Subversion client].
* '''GNU/Linux''': Install the Subversion client via the package manager. This will usually be in a package called <code>subversion-*.{rpm,deb}</code>.
** This command should work for the Raspberry Pi platform: <code>sudo apt-get install subversion</code>. It also contains a client.

=== FGAddon directory layout ===
To know how to use the FGAddon repository, an understanding of the repository directory layout is essential.
* <code>/trunk</code>: This base directory is where the in-development versions of the aircraft are located.
* <code>/branches/release-x.y.z/</code>: These directories correspond to the specific stable FlightGear releases.

The [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/ web interface for the FGAddon repository] allows all of the aircraft to be browsed.

=== Download ===
[[File:V22Osprey.jpg|thumb|200px|Aircraft to be downloaded]]
Firstly, choose an aircraft to download. The [[Bell Boeing V-22 Osprey]] will be used in this example.

==== Command line ====

To download the aircraft for FlightGear 2024.1, simply type:
{{#tag:syntaxhighlight|
{{fgaddon co|branch=branches/release-2024.1|path=Aircraft/V22-Osprey|post=}}
| lang = "sh"
}}

To obtain the in-development version, type:
{{#tag:syntaxhighlight|
{{fgaddon co|path=Aircraft/V22-Osprey|post=}}
| lang = "sh"
}}

If all of the ~500 aircraft from the repository are desired - beware that this will be a huge download of over 6 GB - use the following command:
{{#tag:syntaxhighlight|
{{fgaddon co|post=flightgear-fgaddon}}
| lang = "sh"
}}

When using a stable FlightGear release, for example FlightGear 2020.3, to obtain all of the FGAddon aircraft to match the installed FlightGear version, use:
{{#tag:syntaxhighlight|
{{fgaddon co|branch=branches/release-2020.3|post=flightgear-fgaddon}}
| lang = "sh"
}}

==== GUI clients and TortoiseSVN ====

When using one of the Subversion GUIs (graphical user interfaces), simply copy one of the above <code>https://</code> URLs and use that in the GUI (each GUI is different, so see the relevant documentation for help). For the unique TortoiseSVN tool, simply:

* In Windows Explorer, create a new empty folder for the aircraft (or aircraft collection).
* In the new folder, right click and select <code>SVN Checkout...</code>.
* Copy and paste the URL, for example {{fgaddon source|path=Aircraft/V22-Osprey|type=svn|full=1}}, leave all other settings as they are, and import by clicking on <code>OK</code>.

For more details, see the [http://tortoisesvn.net/support.html TortoiseSVN documentation]. Note that there is an option to install the command line tools when installing TortoiseSVN.

=== Flying ===

To use the newly downloaded aircraft, please see the [[Howto:Install aircraft]] article, skipping the instructions for downloading and unzipping the aircraft.

=== Updates ===
With a checked out copy of the <code>/trunk</code> in-development version, the aircraft can be updated to the latest version using the command:
<syntaxhighlight lang="bash">
svn up
</syntaxhighlight>

== Aircraft development ==

{{tip|The FlightGear community encourages aircraft development directly within FGAddon.}}

=== Contact the original aircraft authors ===

The first step for developing and advancing the aircraft of the official FlightGear hangar, or from one of the [[Flightgear_hangars#Aircraft_hangars|private hangars]] for that matter, is to make contact with the original aircraft author(s). Their names can be found within the <code>*-set.xml</code> file, within the <code><authors></code> XML tag. Often the contact email address will be listed in a README file or some other text file in the base aircraft directory. If not, contact can sometimes be established via the [https://lists.sourceforge.net/lists/listinfo/flightgear-devel FlightGear development mailing list]. Contacting the original authors is important to see if the aircraft is currently being actively developed, and if you can join in as part of the development team.

=== SourceForge account ===

To work on the official aircraft collection, a [https://sourceforge.net/user/registration/ SourceForge account] should first be set up. This will allow to either directly commit to the FGAddon repository, if commit access has been been granted, or to work in as part of a SourceForge development team. The registration process is lightning quick and the SourceForge developer infrastructure and developer services will be accessible in under a minute.

=== Commit access ===

Before obtaining commit access, an all-out effort to contact the original author(s) should be made to determine if the aircraft is actively being developed. If this is unsuccessful, sign up for the [https://lists.sourceforge.net/lists/listinfo/flightgear-devel FlightGear development mailing list] and ask for help there. If the aircraft has a current maintainer, you will be directed as to how to proceed with development. Otherwise ask if someone could volunteer to mentor you in the process of becoming an aircraft developer with full commit access.

To obtain commit access, you will first need:
# To demonstrate your capabilities and development skills.
# To show that you understand the [http://www.flightgear.org/flightgear-policy-document/ FlightGear policy document].
# To show an understanding of the GPL licensing issues, and that you can be trusted not to use copyrighted, non-GPL material.
# To earn the trust of the FlightGear community.

These easy to jump over hurdles are simply designed to protect against repository corruption or pollution of the repository with illegal content.

To have your changes committed into the FGAddon repository, you should discuss and coordinate with the original aircraft author, or your mentor, for the best way to proceed. Depending on the [[#Development_scenarios|development scenario]], this maybe by merge request, file transfer, the primitive patch system, or any other convenient way. Once you believe you have proven your capabilities and you are knowledgeable about GPL licensing issues, you should write a mail to the development mailing list asking if you can be granted commit access, providing your SourceForge username.

=== FGAddon commitlog mailing list ===

To follow all changes which occur in the FGAddon repository, subscribe to the dedicated [https://lists.sourceforge.net/lists/listinfo/flightgear-fgaddon-commitlogs Flightgear FGAddon commitlogs mailing list]. One email is sent per commit, as the commit is made.

== Version control tools ==

To access FGAddon and use it for aircraft development, the Subversion or SVN version control tools are needed. Alternatively git-svn provides an interface for those who prefer the git version control tools.

=== Subversion ===

==== Set up ====
The FGAddon aircraft hangar is stored in a remote Subversion repository located on the SourceForge infrastructure, and therefore it is simplest to use the SVN tools for aircraft development and will cause the least problems. See the [[#Preparation|Subversion installation section]] for setting up the tool chain.

==== Repository checkout ====
The first step is to 'checkout' a copy of either the repository trunk or one of the aircraft in the trunk:
<syntaxhighlight lang="bash">
svn co <url> <dir>
</syntaxhighlight>

For the relevant URL to use, you must chose one of the [[#Development_scenarios|development scenarios]] and find the URL in that section. This command will create a local subversion repository copy in the given <code><dir></code> directory. Note that this will only contain the part of the FGAddon repository specified in the URL. This means that Subversion allows you to checkout either a single file all the way to the entire remote repository.

==== Information and history ====
At any point to see information about the local repository, type:
<syntaxhighlight lang="bash">
svn info
</syntaxhighlight>

To see the history of the checked out copy of the repository, type one of:
<syntaxhighlight lang="bash">
svn log
svn log | less
svn log -v | less
</syntaxhighlight>

==== Daily usage ====
The main Subversion command you will be using is:
<syntaxhighlight lang="bash">
svn add <path>
</syntaxhighlight>

This will register the file or directory <code><path></code> within the local repository to allow it to later be 'committed' and sent to the remote repository. To move or rename a file or directory, use:
<syntaxhighlight lang="bash">
svn mv <path1> <path2>
</syntaxhighlight>

This should be used rather than normal file moving/renaming so that the change is tracked in the local repository. To remove a file from the local repository, type:
<syntaxhighlight lang="bash">
svn rm <path>
</syntaxhighlight>

To see the current status of the local repository, type:
<syntaxhighlight lang="bash">
svn st
</syntaxhighlight>

To update the local repository with changes in the remote repository, type:
<syntaxhighlight lang="bash">
svn up
</syntaxhighlight>

==== Committing changes ====
All of the above operations only occur on the local repository copy - the remote FGAddon repository at SourceForge will know nothing of these changes. To send all your changes to FGAddon, you need to commit the changes:
<syntaxhighlight lang="bash">
svn ci
</syntaxhighlight>

This will open up an editor to allow you to write an informative commit log message. When committing, it is best to make small modular commits so that each commit corresponds to a single purpose. Note that you can only commit to FGAddon if you have [[#Commit access|commit access]].

==== Branching ====
The concept of Subversion branching is currently only used in the FlightGear project for tagging the stable releases. However if you are curious about branching, see the [http://svnbook.red-bean.com/en/1.7/svn.branchmerge.html Branching and Merging chapter of the Subversion manual], and the [https://www.orcaware.com/svn/wiki/Svnmerge.py svnmerge.py script] which can greatly simplify the process.

=== Git-svn ===

The git-svn tool is useful for those who are already familiar with using git repositories, or those who wish to have their own private aircraft development playground. Git-svn provides a bridge between the remote FGAddon Subversion repository and a local git repository. For those unfamiliar with git, the git-svn bridge together with the git repository is far more complicated to use than the native [[#Subversion|Subversion tools]]. For more information on using git, see [[Howto:Start using git]]. The following will assume that only a single aircraft will be stored in the local git repository.

==== Set up ====
The git distributed version control system needs to first be [https://git-scm.com/downloads installed].

==== Cloning a single aircraft ====
The first step is to 'clone' a copy of one of the aircraft in the remote Subversion trunk:
<syntaxhighlight lang="bash">
git svn clone <aircraft_url>
</syntaxhighlight>

For the relevant aircraft URL to use, you must chose one of the [[#Development_scenarios|development scenarios]] and find the URL in that section. The URL depends on your [[#Commit access|FGAddon commit access status]]. The clone command will create a local git repository containing solely the aircraft of interest, and initialise the git-svn bridge.

==== Information and history ====
At any point to see information about the local repository, type:
<syntaxhighlight lang="bash">
git svn info
git branch -vva
git remote -v
</syntaxhighlight>

To see the history of the checked out copy of the repository, type:
<syntaxhighlight lang="bash">
git log
</syntaxhighlight>

==== Daily usage ====
The main git command you will be using is:
<syntaxhighlight lang="bash">
git add <path>
</syntaxhighlight>

This will register the file or directory <code><path></code> within the local repository to allow it to later be 'committed' to the local git repository. To move or rename a file or directory, use:
<syntaxhighlight lang="bash">
git mv <path1> <path2>
</syntaxhighlight>

However note that git history is not as robust as svn history. See the [[#Moving_or_renaming_files|git-svn file moving/renaming deficiency section]] for how to better perform this operation. To remove a file from the local repository, type:
<syntaxhighlight lang="bash">
git rm <path>
</syntaxhighlight>

To see the current status of the local repository, type:
<syntaxhighlight lang="bash">
git status
</syntaxhighlight>

==== Committing changes ====
As git is a distributed version control system, changes are committed to the local git repository.
<syntaxhighlight lang="bash">
git commit
</syntaxhighlight>

This will open up an editor to allow you to write an informative commit log message. The commit is local and will not be sent to FGAddon.

==== Dedicated FGAddon branch ====
In the examples above, only a single branch was assumed in the repository. If interaction with a remote git repository or branching within the local git repository is desired, then a different strategy is required. The reason being that the branch that synchronises with FGAddon must [https://git-scm.com/book/en/v1/Git-and-Other-Systems-Git-and-Subversion#git-svn preserve a linear history]. This means only cherry-picking of the desired changes into that branch is allowed.

In this example, two branches will be set up in the local git repository:
* <code>fgaddon</code>: This branch will be dedicated for FGAddon synchronisation and will preserve a linear history.
* <code>master</code>: A master branch for aircraft development, allowing for mergers and other non-linear history operations.

Assuming a [[#Cloning_a_single_aircraft|newly cloned repository]], create the <code>fgaddon</code> branch with:
<syntaxhighlight lang="bash">
git branch fgaddon
</syntaxhighlight>

And switch to that branch:
<syntaxhighlight lang="bash">
git checkout fgaddon
</syntaxhighlight>

The FGAddon synchronisation can then be performed on this branch. To pull in the developments from the master branch, use cherry-picking to apply a sequentially ordered list of commit hashes:
<syntaxhighlight lang="bash">
git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...
</syntaxhighlight>

To see the list of commits to be sent to FGAddon prior to dcommitting, type:
<syntaxhighlight lang="bash">
git log git-svn..HEAD
</syntaxhighlight>

And to see the changes as a single diff:
<syntaxhighlight lang="bash">
git diff git-svn..HEAD
</syntaxhighlight>

==== Synchronising ====
To send the changes to the remote FGAddon repository, firstly change to the dedicated <code>fgaddon</code> branch:
<syntaxhighlight lang="bash">
git checkout fgaddon
</syntaxhighlight>

Make sure the local git-svn repository is up to date with all changes that have occurred in FGAddon:
<syntaxhighlight lang="bash">
git svn rebase
</syntaxhighlight>

Then push or dcommit the changes to FGAddon with:
<syntaxhighlight lang="bash">
git svn dcommit
</syntaxhighlight>

=== Deficiencies of git-svn ===

{{warning|Performing a <code>git-svn clone</code> of the <code>/trunk/</code> or entire repository is not recommended, as the entire repository history will be downloaded, resulting in a huge local repository, as well as putting a large strain on the FlightGear open source infrastructure.}}

It is important to understand that there are a number of operations in which git-svn is deficient. In many cases, the svn tools should be used instead.

==== Copying files between aircraft ====

{{caution|Git-svn does not maintain the file copying history normally present in a Subversion repository.}}

The most important of these is the copying of content from other FGAddon aircraft. In this case you will need FGAddon commit access and a local svn copy of the repository. Firstly synchronise the repositories by dcommitting all changes back to FGAddon:
<syntaxhighlight lang="bash">
git svn dcommit
</syntaxhighlight>

Then in the local svn repository, copy the file:
<syntaxhighlight lang="bash">
svn cp Aircraft/<aircraft1>/<file_path1> Aircraft/<aircraft2>/<file_path2>
</syntaxhighlight>

And commit the change:
<syntaxhighlight lang="bash">
svn ci
</syntaxhighlight>

Back in the local git-svn repository, pull in the new files:
<syntaxhighlight lang="bash">
git svn rebase
</syntaxhighlight>

Using the subversion tools avoids the FGAddon repository backend from significantly increasing in size, as [http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html#svn.branchmerge.using.create svn copies are cheap].

==== Moving or renaming files ====

{{caution|Git-svn does not always maintain the file moving or renaming history normally present in a Subversion repository.}}

This problem stems from the fact that svn history is more robust than that of git. The <code>svn mv</code> and <code>git mv</code> commands are not equivalent. The subversion command stores the move history directly in the repository whereas git does not (git instead uses heuristic methods to try to detect history, after the commit). The result of using git-svn is that often the move will not be detected and the FGAddon history will show one file or directory being deleted and another added. This also causes the repository backend to increase in size, whereas <code>svn mv</code> will not cause any significant size increase. If you wish to have a better historical record in the FGAddon repository and be considerate to the repository backend, it is recommended that you temporarily switch to the subversion tools. Firstly, synchronise the repositories:
<syntaxhighlight lang="bash">
git svn dcommit
</syntaxhighlight>

Then in the local svn repository, move or rename the file:
<syntaxhighlight lang="bash">
svn mv Aircraft/<aircraft>/<file_path1> Aircraft/<aircraft>/<file_path2>
</syntaxhighlight>

And commit the change:
<syntaxhighlight lang="bash">
svn ci
</syntaxhighlight>

Back in the local git-svn repository, pull in the changes with:
<syntaxhighlight lang="bash">
git svn rebase
</syntaxhighlight>

==== Copying files within one aircraft ====

Just as the <code>svn mv</code> command stores the move information directly within the repository, so does <code>svn cp</code> store the copy information. Therefore if you would like to duplicate a text file and modify it, using the native Subversion tools instead of git-svn for this operation allows for the file history to be permanently preserved in the FGAddon repository.

==== Subversion properties ====

{{caution|Git-svn currently only supports the <code>svn:executable</code> property, all other properties are ignored and cannot be added, changed, or removed in a git-svn clone of the aircraft.}}

Internally, Subversion identifies binary files using the <code>svn:mime-type</code> repository property. However as git-svn cannot set this property when using the <code>git add</code> command, the result is that binary files will be treated as text. Binary diffs will be seen when using <code>svn diff</code> or <code>git diff</code>, and a binary diff will be shown in the [[#FGAddon commitlog mailing list|FGAddon commitlog mailing list]] messages. As this issue is not unique to git-svn, to work around this issue please see the [[#Binary diffs|binary diffs]] section.

==== Protocols other than svn+ssh ====

The command <code>git svn init</code> replicates the entire history of an aircraft into a local repository. As part of this process, it generates a git commit ID or hash for every Subversion revision. The problem is that the git commit ID depends on the protocol used to read from the Subversion repository (likely a git bug). Hence:

{{#tag:syntaxhighlight|
{{fgaddon source|cmd=git svn init|protocol=svn+ssh|login=<username>|type=svn|path=Aircraft/<aircraft>|full=1}}
| lang = "sh"
}}

and

{{#tag:syntaxhighlight|
{{fgaddon source|cmd=git svn init|protocol=https|type=svn|path=Aircraft/<aircraft>|full=1}}
| lang = "sh"
}}

will result in two different and incompatible git repositories, even though they contain the same data. The incompatibility is not immediately apparent but it will bite later. Suppose someone with read-only access to FGAddon uses the https method, then asks a FGAddon gatekeeper to commit their changes. The gatekeeper, naturally, uses svn+ssh, as this is the only protocol granting write permissions. When the gatekeeper tries to merge the contributor's https clone into their own svn+ssh clone, git will complain that the two repositories have no history in common, and flag every change as a conflict.

Therefore, if you are planning to make any changes to an aircraft, be sure to use svn+ssh even if you do not yet have commit permissions on FGAddon. svn+ssh does not require write permissions, it only requires a SourceForge user ID.

== FGAddon development concepts ==

=== New aircraft ===

To add a new aircraft to the FGAddon repository, the SVN tools are required. If you encounter <code>svn:mime-type</code> property problems when adding a new aircraft, see the [[#Mime-type problems|mime-type problems section]] for how to resolve the issue. Or if you have a <code>svn:executable</code> property problem, see the [[#Executable flag|executable flag problem section]].

==== svn import ====

{{warning|The <code>svn import</code> command described herein will send all contents of the specified directory directly into FGAddon without warning and without a way to cancel the operation. Therefore special care must be taken when specifying the directory to upload into FGAddon, as well as the target FGAddon directory. See the [[#svn add|svn add]] section below for a safer way to add a new aircraft.}}

The [http://svnbook.red-bean.com/en/1.7/svn.tour.importing.html#svn.tour.importing.import svn import] command is the easiest method to use and does not require a local copy of the repository to be checked out. To start:

# Create an empty local aircraft directory.
# Copy the aircraft files into this directory.
# Carefully check all files to make sure there are no hidden or temporary files that should not be uploaded to FGAddon.

Assuming the Dead Simple Human Powered Airplane (DaSH PA or "DaSH") aircraft as an example, located in the <code>DaSH/</code> directory, on the command line run:
{{#tag:syntaxhighlight|
{{fgaddon source
| cmd = svn import DaSH/
| protocol = svn+ssh
| login = <username>
| type = svn
| path = Aircraft/DaSH/
| post = -m \
| full = 1
}}
"Initial import of the DaSH human powered aircraft.\n\nFor details see the forum thread at http://forum.flightgear.org/viewtopic.php?f=4&t=24495 ."
| lang = "sh"
}}

Where <code><username></code> is the SourceForge user name. This will add all the files into FGAddon with commit log message with the summary line <code>Initial import of the DaSH human powered aircraft.</code>, followed by a blank line, and then a detailed description pointing to the original location or discussion of the aircraft. To see if the aircraft has been successfully added to the repository:
{{#tag:syntaxhighlight|
{{fgaddon source
| cmd = svn list
| protocol = svn+ssh
| login = <username>
| type = svn
| path = Aircraft/DaSH/
| full = 1
}}
| lang = "sh"
}}

Or visit the {{fgaddon source|path=Aircraft|text=FGAddon web interface}}. The aircraft can then be checked out as described in the [[#Development scenarios|Development scenarios section]].

==== svn add ====

If a local copy of the FGAddon trunk is present, then the <code>svn add</code> command can be used instead. This is far safer than the <code>svn import</code> command, as the change can be double checked before committing. In the <code>Aircraft/</code> directory of the local repository, create the <code>DaSH/</code> directory. This can either be empty or contain all files of the initial aircraft. Then on the command line, add the aircraft to the local repository:
<syntaxhighlight lang="bash">
svn add DaSH/
</syntaxhighlight>

Then double check the changes prior to committing:
<syntaxhighlight lang="bash">
svn st
</syntaxhighlight>

And send the changes to FGAddon with:
<syntaxhighlight lang="bash">
svn ci
</syntaxhighlight>

An editor, often vi<ref>[http://www.vim.org/docs.php Vim documentation]</ref>, will open and the commit message can be composed. Alternatively the commit log message can be specified on the command line with:
<syntaxhighlight lang="bash">
svn ci -m "<subject_line>\n\n<detailed_description>"
</syntaxhighlight>

=== Commit blocking by pre-commit hooks ===

Sometimes when committing to FGAddon, the commit will be blocked the following will be printed out:
<pre>
svn: E165001: Commit failed (details follow):
svn: E165001: Commit blocked by pre-commit hook (exit code 1) with output:
</pre>

This is due to the presence of two repository pre-commit hook scripts which check the quality of the commit, blocking it if a text file is set to a binary file mime-type or if the executable flag is set. These scripts are simply to protect the repository and to keep it clean.

==== Mime-type problems ====

Sometimes when attempting to commit files to FGAddon using the SVN tools, the commit will be blocked with the following message:
<pre>
Sending dash-set.xml
svn: E165001: Commit failed (details follow):
svn: E165001: Commit blocked by pre-commit hook (exit code 1) with output:

Aborting the commit, the svn:mime-type property is labelling the following text
files as binary:

dash-set.xml: svn:mime-type=application/xml

Before committing, please remove this property by typing 'svn propdel svn:mime-
type file_name' for all affected files. This will allow the text files to be
treated as text within the FGAddon repository.

To avoid the svn:mime-type property being incorrectly set by your subversion
client, the subversion configuration file at $HOME/.subversion/config or
%appdata%\roaming\subversion\config should be edited and a new entry added to
[auto-props] for each affected file type. In most cases, the problem is with
XML files being labelled as "application/xml" by a library called libmagic. To
override this, add the following to the svn config file:

*.xml = svn:mime-type=text/xml

svn: E165001: Your commit message was left in a temporary file:
svn: E165001: '/flightgear/repo_testing/svn-commit.tmp'
</pre>

Despite messages about adding or sending files, no change will have occurred in the FGAddon repository. This message is created by a repository pre-commit hook script which checks if the Subversion <code>svn:mime-type</code> property is set on a list of known text files and, if the mime-type is set to a binary format, the commit is blocked. The reason for this block is to protect the repository. Newer SVN clients rely on a 3rd party library known as libmagic which will detect the aircraft XML files as the binary mime-type of <code>application/xml</code>. The result is that the XML files are treated as binary files in the repository. This behaviour is completely undesirable, as changes cannot be followed on the [[#FGAddon commitlog mailing list|flightgear-fgaddon-commitlogs mailing list]] or in the repository history, and the size of the commits become orders of magnitude larger. Therefore this buggy behaviour has been blocked for the protection of the FlightGear project. To remove the problem, follow the instructions in the message and, using the command line tools, type:
<syntaxhighlight lang="bash">
svn propdel svn:mime-type <file_name>
</syntaxhighlight>

Repeat this for each text file listed in the error message. Then commit again, using the commit message saved in the <code>svn-commit.tmp</code> file. The message file name will be reported in the commit failure message, but check its contents first:
<syntaxhighlight lang="bash">
cat svn-commit.tmp
</syntaxhighlight>

And reperform the commit:
<syntaxhighlight lang="bash">
svn ci -F svn-commit.tmp
</syntaxhighlight>

===== Subversion config file =====

The automatic property setting of <code>svn:mime-type</code> can be controlled by modifying the Subversion <code>config</code> file. Firstly in the <code>[miscellany]</code> section, make sure that the auto-properties are turned on:
<syntaxhighlight>
enable-auto-props = yes
</syntaxhighlight>

Then in the <code>[auto-props]</code> section, add:
<syntaxhighlight>
*.ac = svn:mime-type=text/plain
*.eff = svn:mime-type=text/xml
*.frag = svn:mime-type=text/plain
*.nas = svn:mime-type=text/plain
*.osgx = svn:mime-type=text/xml
*.svg = svn:mime-type=text/svg+xml
*.txt = svn:mime-type=text/plain
*.vert = svn:mime-type=text/plain
*.xhtml = svn:mime-type=text/xml
*.xml = svn:mime-type=text/xml
*.xsl = svn:mime-type=text/xml
</syntaxhighlight>

These are all the text files that the hook script will check that the mime-type is set to a text format, though new text files will likely be added in the future. These additions can either be to the user configuration file located at <code>~/.subversion/config</code> (or <code>%USERPROFILE%\AppData\Roaming\Subversion\config</code> in Windows) or, if a user configuration file is not set, to the global configuration file at <code>/etc/subversion/config</code> (or <code>%APPDATA%\Subversion\config</code> in Windows).

==== Executable flag ====

Another blocking message when attempting to commit files to FGAddon using the SVN tools is:
<pre>
Adding dash-set.xml
Transmitting file data .svn: E165001: Commit failed (details follow):
svn: E165001: Commit blocked by pre-commit hook (exit code 1) with output:

The svn:executable property is set on the files ['dash-set.xml'], aborting the
commit.

The current policy is that no executable files are allowed in FGAddon. Before
committing, please remove this property by typing 'svn propdel svn:executable
file_name' for all affected files. Or to remove it recursively from all files
to be committed, in your aircraft directory type 'svn propdel svn:executable
-R'.

To avoid the svn:executable property being set by your subversion client, on
GNU/Linux and Mac OS X systems simply make sure that the file's execute bit is
not set before adding the file to be committed.

svn: E165001: Your commit message was left in a temporary file:
svn: E165001: '/flightgear/repo_testing/svn-commit.tmp'
</pre>

This will probably only be seen on Mac OS X and GNU/Linux systems. This message is printed by a pre-commit repository hook script that checks if the Subversion <code>svn:executable</code> property is set and, if so, the commit is blocked. This is a security measure, as no aircraft files should be executable. To remove the problem, follow the instructions in the message and, using the command line tools, type:
<syntaxhighlight lang="bash">
svn propdel svn:executable -R
</syntaxhighlight>

Then commit again, using the commit message saved in the <code>svn-commit.tmp</code> file. The message file name will be reported in the commit failure message, but check its contents first:
<syntaxhighlight lang="bash">
cat svn-commit.tmp
</syntaxhighlight>

And the reperform the commit:
<syntaxhighlight lang="bash">
svn ci -F svn-commit.tmp
</syntaxhighlight>

=== Binary diffs ===

{{warning|The incorrect setting or absence of the mime-type property on a binary file will result in a binary diff.}}

When looking at the output of <code>svn diff</code> (or <code>git diff</code> if you are using git-svn) as well as when reading messages from the [[#FGAddon commitlog mailing list|FGAddon commitlog mailing list]], you may see a large number of unrecognisable characters. This is the result of what is known as a binary diff, showing the binary file differences as if it were text. Although this is not a issue for the operation of the repository, the situation is an aesthetic problem which makes it more difficult to perform a review of the changes.

To fix the problem, firstly the binary files with the <code>svn:mime-type</code> property missing need to be identified. The following subversion command can be used:
<syntaxhighlight lang="bash">
svn propget svn:mime-type <file_name>
</syntaxhighlight>

As it can be tedious checking each file individually, the following Python script simplifies and automates the process to identify all binary files with a mime-type issue:

{{collapsible script
| type = Python 2/3 script
| title = Find binary files with no <code>svn:mime-type</code> property set.
| intro = The following script is based on blacklisting text files. Hence false positives are to be expected, and the blacklists can be expanded as needed.
| lang = python
| script =
#! /usr/bin/env python

from os import getcwd, walk
from os.path import join, splitext
from re import search
from subprocess import PIPE, Popen

skip_txt_file_seg = [
'authors',
'copying',
'licen',
'readme'
]

skip_txt_ext = [
'ac',
'css',
'dat',
'eff',
'frag',
'html',
'json',
'log',
'nas',
'osgx',
'svg',
'tex',
'txt',
'vert',
'xhtml',
'xml',
'xsl'
]

skip_bin_prop = [
'application/octet-stream',
'application/pdf',
'application/postscript',
'application/x-dosexec',
'application/x-gzip',
'application/zip',
'audio/x-wav',
'image/gif',
'image/jpeg',
'image/png',
'image/vnd.adobe.photoshop',
'image/tiff',
'image/x-ms-bmp',
'image/x-xcf',
]

# Walk through the directories.
for root, dirs, files in walk(getcwd()):
# Loop over the files in the current directory.
for file in files:
# Skip known text files.
skip = False
for i in range(len(skip_txt_file_seg)):
if search(skip_txt_file_seg[i], file.lower()):
skip = True
if skip:
continue

# The file extension.
file_path, ext = splitext(file)
ext = ext[1:].lower()

# Skip known text file extensions.
if ext in skip_txt_ext:
continue

# The full file path.
path = join(root, file)

# Query the file for svn:mime-type.
cmd = 'svn propget svn:mime-type \"%s\"' % path
pipe = Popen(cmd, shell=True, stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=False)
props = []
for line in pipe.stdout.readlines():
props.append(line.strip())

# Byte array conversion (Python3).
for i in range(len(props)):
if hasattr(props[i], 'decode'):
props[i] = props[i].decode()

# Skip binary svn:mime-type values.
if len(props) and props[0] in skip_bin_prop:
continue

# Printout.
if not len(props):
print("%s" % path)
else:
print("%s svn:mime-type=%s" % (path, props[0]))
}}

==== Fixing the problem ====

As [[#Subversion_properties|git-svn cannot set or change]] the <code>svn:mime-type</code> property, a [[#Repository_checkout|svn checkout copy]] of the aircraft is required. The property can then be set to the default Subversion binary mime-type with:
<syntaxhighlight lang="bash">
svn propset svn:mime-type "application/octet-stream" <file_name>
</syntaxhighlight>

Alternatively, the following set of shell commands can be used to automate the process:
{{collapsible script
| type = Shell commands
| title = Set specific <code>svn:mime-type</code> values on a set of known binary files.
| intro = These shell commands will work on GNU/Linux or Mac OS X systems (or on Windows if using cygwin, or if a find command line tool is installed). The list of file types here are those most commonly found in FGAddon. To set the property on a list of binary files, type (or copy and paste):
| lang = bash
| script =
find -iname "*.wav" -exec svn propset svn:mime-type "audio/x-wav" {} \;
find -iname "*.bmp*" -exec svn propset svn:mime-type "image/x-ms-bmp" {} \;
find -iname "*.gif" -exec svn propset svn:mime-type "image/gif" {} \;
find -iname "*.jpg" -exec svn propset svn:mime-type "image/jpeg" {} \;
find -iname "*.png*" -exec svn propset svn:mime-type "image/png" {} \;
find -iname "*.psd" -exec svn propset svn:mime-type "image/vnd.adobe.photoshop" {} \;
find -iname "*.tif" -exec svn propset svn:mime-type "image/tiff" {} \;
find -iname "*.xcf" -exec svn propset svn:mime-type "image/x-xcf" {} \;
find -iname "*.rgb*" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.au" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.*af" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.3ds" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.blend*" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.dds" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.od[gst]" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.onetoc2" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.xlsx" -exec svn propset svn:mime-type "application/octet-stream" {} \;
find -iname "*.pdf" -exec svn propset svn:mime-type "application/pdf" {} \;
find -iname "*.ps" -exec svn propset svn:mime-type "application/postscript" {} \;
find -iname "*.gz" -exec svn propset svn:mime-type "application/x-gzip" {} \;
find -iname "*.mdl" -exec svn propset svn:mime-type "application/x-dosexec" {} \;
find -iname "*.zip" -exec svn propset svn:mime-type "application/zip" {} \;
| conc = Other binary files can safely be set to <code>"application/octet-stream"</code>, the Subversion default for binary files.
}}

== SourceForge developer services ==

The FlightGear project is hosted on the SourceForge open source infrastructure. This developer services section will highlight some of the useful tools you can take advantage of. SourceForge consists of two categories of services:
; Project infrastructure : The FlightGear project uses the project services of SourceForge. These services are for standalone software projects.
; Developer infrastructure : These are services available to anyone with a SourceForge account, and are available via your SourceForge homepage and accessible to all. This includes being able to create multiple version control repositories (svn, git, hg), wikis, forums, development teams, blogs, and ticket trackers (for bugs, support requests, tasks, etc.).

Rather than creating a new project, any development for the FlightGear project should be based on the developer infrastructure.

=== Developer git repository ===

To set up your own remote git repository, here for developing the FGAddon fkdr1 aircraft:
* On your profile page at <tt><nowiki>https://sourceforge.net/u/<username>/profile/</nowiki></tt>, go to <code>Admin</code> -> <code>Add New</code> -> <code>Git</code>.
* Set label to <code>fkdr1 FGAddon git-svn repository</code>.
* Set the code path to <code>code-fkdr1</code>. The <code>code-*</code> prefix is to differentiate this from the <code>forum-*</code>, <code>wiki-*</code>, and other directories.

The repository will be located at <tt><nowiki>https://sourceforge.net/u/<username>/code-fkdr1/ci/master/tree/</nowiki></tt>.

=== Development teams ===

If you and a group of friends would like to privately develop one of the FGAddon aircraft as a team, assuming that the you have contacted the original aircraft authors and the aircraft is not actively being developed, then you should create a SourceForge development team. A team leader should be appointed to set this up under their SourceForge account. Assuming you wish to develop the "ornithopter" aircraft, the steps are:

* Go to <code>Personal tools</code> -> <code>Admin</code>.
* Click on <code>User Permissions</code>.
* Click on <code>Add a new group</code> at the bottom.
* Set the name to <code>ornithopter</code>, and save.
* Click on <code>Add</code> in the <code>ornithopter</code> group and add the SourceForge names of all your team members.

After setting up a private repository in the team leader's account, as described below, then the development team should be set up for the repository.

* Go to the repository under your SourceForge account.
* Click on <code>Admin - <repository name></code>, then select <code>Permissions</code>.
* In the <code>Write</code> section, remove <code>Developer</code> and add <code>ornithopter</code>.
* Click on <code>Save</code>.

The development team will then have commit access to the private repository.

=== Team communications ===

To help with team development, the SourceForge infrastructure allows for multiple [https://sourceforge.net/p/forge/documentation/Discussion/ dedicated discussion forums] to be created. This can either be within a SourceForge project or under a SourceForge users homepage. This allows the team leader to create a forum dedicated solely to the development of the aircraft of interest. Continuing with the <code>ornithopter</code> example, the steps for the team leader are simple:

* On your profile page at <tt><nowiki>https://sourceforge.net/u/<username>/profile/</nowiki></tt>, go to <code>Personal tools</code> -> <code>Admin</code>.
* Click on the <code>Tools</code> option in the left hand menu.
* Click on <code>Discussion</code> in the <code>Click to install</code> section.
* Change the label to <code>Ornithopter forum</code>, and the path to <code>forum-ornithopter</code>, for example. The <code>forum-*</code> prefix is to differentiate this from the <code>code-*</code>, <code>wiki-*</code>, and other directories.
* Click on <code>Save</code>.

More details are given on the [https://sourceforge.net/p/forge/documentation/Discussion/ SourceForge Discussion documentation].

== Development scenarios ==

=== Individual developer ===

{{Note|Development scenario: You are an individual developer and will use the native Subversion tools.}}

This is by far the simplest development scenario and should be used in most cases. If you are using the command line Subversion client, you can checkout an individual aircraft with:
{{#tag:syntaxhighlight|
{{fgaddon co
| login = <username>
| path = Aircraft/wrightFlyer1903
| post =
}}
| lang = "sh"
}}

Where <code><username></code> is your SourceForge user name. Alternatively you can checkout all aircraft with:
{{#tag:syntaxhighlight|
{{fgaddon co
| login = <username>
| post = flightgear-fgaddon
}}
| lang = "sh"
}}

If you do not have commit access, type one of:
{{#tag:syntaxhighlight|
{{fgaddon co
| path = Aircraft/wrightFlyer1903
| post =
}}
{{fgaddon co
| post = flightgear-fgaddon
}}
| lang = "sh"
}}

To use the new local svn repository, see the [[#Subversion|subversion instructions]].

=== Individual developer (git-svn) ===

{{Note|Development scenario: You are an individual developer and will use the git-svn tools.}}

This is more complicated than using the native SVN tools, but can be useful without having FGAddon commit access, as multiple local commits can be made to be sent to the original aircraft authors or to the development mailing list/forum. To clone the aircraft of choice into a new git repository, type:
{{#tag:syntaxhighlight|
{{fgaddon source|cmd=git svn clone|protocol=svn+ssh|login=<username>|type=svn|path=Aircraft/<aircraft>|full=1}}
| lang = "sh"
}}

Where <code><username></code> is your infrastructure user name and <code><aircraft></code> is the directory name in the FGAddon repository. This is valid whether or not you have commit permissions.

To use the new local git repository, see the [[#Git-svn|git-svn instructions]] and [[#Deficiencies_of_git-svn|its deficiencies]].

==== Upload to Sourceforge ====

To share the local developments, the changes can be uploaded to a remote git repository on the SourceForge infrastructure. For this, a [[#Developer_git_repository|developer git repository]] should first be set up under your SourceForge profile. Then add this as a remote:
{{#tag:syntaxhighlight|
{{sourceforge url|cmd=git remote add|opt=origin|protocol=ssh|login=<username>|user=<username>|type=git|repo=code-<aircraft>}}
| lang = "sh"
}}

And send the master branch where developments are located with:
<syntaxhighlight lang="bash">
git push --set-upstream origin master
</syntaxhighlight>

The changes in the new repository will be visible via the web interface at {{#tag:span|{{#tag:tt|{{#tag:nowiki|{{sourceforge url|user=<username>|repo=code-<aircraft>|branch=master}}}}}}| style="color: blue"}}.

=== Sending external git repository changes into FGAddon ===

{{Note|Development scenario: You are an individual developer with FGAddon commit access and wish to transfer the commits in a remote git repository into FGAddon using a temporary local git repository.}}

Firstly clone the FGAddon aircraft into a local git-svn repository with:
{{#tag:syntaxhighlight|
{{fgaddon source|cmd=git svn clone|protocol=svn+ssh|login=<username>|type=svn|path=Aircraft/<aircraft>|full=1}}
| lang = "sh"
}}

This will create a new local git repository linked to FGAddon via git-svn. If the aircraft is new and not present in FGAddon, see the [[#New_aircraft|instructions for adding a new aircraft to FGAddon]]. Next, set up the remote git repository as a remote, and fetch it:
<syntaxhighlight lang="bash">
git remote add <name> <url>
git fetch
</syntaxhighlight>

Where <code><url></code> is the URL of the remote git repository. Finally make an ordered list of all hashes of the commits to be sent into FGAddon, from earliest to latest, and cherry-pick them into the git-svn master branch:
<syntaxhighlight lang="bash">
git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...
</syntaxhighlight>

Note that the git-svn local repository should only have a single <code>master</code> branch and only consist of cherry-picking. To see the changes queued for sending to FGAddon:
<syntaxhighlight lang="bash">
git log git-svn..HEAD
git diff git-svn..HEAD
</syntaxhighlight>

Then to send the changes to FGAddon, firstly pull in any remote changes, and send the commits:
<syntaxhighlight lang="bash">
git svn rebase
git svn dcommit
</syntaxhighlight>

The temporary local repository can then be deleted.

=== Connecting an existing git repository to FGAddon ===

{{Note|Development scenario: You are an individual developer or team leader with FGAddon commit access and wish to connect a pre-existing remote git repository with FGAddon to send all changes back to FGAddon.}}

If a remote git repository containing a developed aircraft already exists, it is possible to connect it to the remote FGAddon repository using the git-svn tools. The following uses the [[#Dedicated_FGAddon_branch|dedicated FGAddon branch technique]]. Firstly, set up the bridge to FGAddon using git-svn in the per-aircraft repository:
{{#tag:syntaxhighlight|
{{fgaddon source|cmd=git svn init|protocol=svn+ssh|login=<username>|type=svn|path=Aircraft/<aircraft>|full=1}}
| lang = "sh"
}}

Where <code><aircraft></code> is the aircraft directory name in FGAddon. Note that this step can be performed without commit access to FGAddon by using a read-only SVN URL instead, but then changes cannot be pushed back to FGAddon ([[#Synchronising|dcommitting]], as it is known in the git-svn terminology). However, this allows upstream FGAddon changes to be integrated into the remote git repository, thus making it easy to prepare changes for submission for FGAddon inclusion using patches sent to the mailing list or sent via other channels.

Now fetch the current state from the remote FGAddon repository:
<syntaxhighlight lang="bash">
git svn fetch
</syntaxhighlight>

The downloaded SVN history is in the remote branch <code>remotes/git-svn</code>. To commit changes to SVN you need a local branch that tracks this remote branch. Create a local <code>fgaddon</code> branch that you will use to commit updates:
<syntaxhighlight lang="bash">
git branch fgaddon remotes/git-svn
</syntaxhighlight>

After committing new stuff to the <code>master</code> branch, to push to FGAddon checkout the <code>fgaddon</code> branch and update it from SVN in case someone else has touched the aircraft in the remote FGAddon repository:
<syntaxhighlight lang="bash">
git checkout fgaddon
git svn rebase
</syntaxhighlight>

Cherry-pick the new commits from <code>master</code> to <code>fgaddon</code> to preserve a linear history:
<syntaxhighlight lang="bash">
git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...
</syntaxhighlight>

To see the changes queued for sending to FGAddon as either commits or a diff, type:
<syntaxhighlight lang="bash">
git log git-svn..HEAD
git diff git-svn..HEAD
</syntaxhighlight>

If everything looks ok, dcommit the local commits on the <code>fgaddon</code> branch to send them to the remote FGAddon SVN repository:
<syntaxhighlight lang="bash">
git svn dcommit
</syntaxhighlight>

Switch back to the master branch for local development:
<syntaxhighlight lang="bash">
git checkout master
</syntaxhighlight>

To get changes from upstream you can either just download them with
<syntaxhighlight lang="bash">
git svn fetch
</syntaxhighlight>

or download them and rebase your <code>fgaddon</code> branch onto them:
<syntaxhighlight lang="bash">
git checkout fgaddon
git svn rebase
</syntaxhighlight>

=== Team development ===

{{Note|Development scenario: All members of the team are acting as gatekeepers, and all commits are made directly to FGAddon, either using svn or git-svn.}}

The simplest way to work as a team is for each developer to either have a [[#Individual developer|svn copy of FGAddon]] or a [[#Individual developer (git-svn)|git-svn copy of FGAddon]], and everyone commits directly to FGAddon. Communication and coordination between the team members can be performed using a [[#Team_communications|team leader organised SourceForge forum]] or using the [http://forum.flightgear.org/ FlightGear forum]. In this scenario, the team needs to take the initiative and everyone apply for FGAddon commit access.

=== Private team development (git-svn) ===

{{Note|Development scenario: One team leader is acting as the gatekeeper on a private git repository hosted on the in-house SourceForge infrastructure, using git-svn to push a fgaddon branch to FGAddon, with team members committing directly to the private git repository or making merge requests from their fork of the private repository.}}

To keep everything in-house, the entire operation will be based on the official infrastructure and remote repositories under each user's SourceForge (SF) profile. Note to the team leader - you must [https://git-scm.com/book/en/v1/Git-and-Other-Systems-Git-and-Subversion#git-svn keep your git-svn history linear] (meaning that a [[#Dedicated_FGAddon_branch|dedicated FGAddon branch]] should be created and changes manually cherry-picked into this branch). In the following, the <code>ornithopter</code> aircraft will be used as an example.

==== The team ====

Firstly, the entire team should sign up for [[#SourceForge account|SourceForge accounts]].

==== Team leader ====

===== Private repository set up =====

These steps are to be taken by the team leader. In your SourceForge user profile, set up a [[#Developer_git_repository| git repository]] with the label <code>Ornithopter FGAddon git-svn repository</code> and code path <code>code-ornithopter</code>. Then create a empty local git repository:
<syntaxhighlight lang="bash">
$ mkdir ornithopter
$ cd ornithopter
$ git init
</syntaxhighlight>

Link the empty repository to the <code>ornithopter</code> aircraft directory in the remote FGAddon repository and pull it in with:
{{#tag:syntaxhighlight|
$ {{fgaddon source|cmd=git svn init|protocol=svn+ssh|login=<username>|type=svn|path=Aircraft/ornithopter|full=1}}
$ git svn fetch
| lang = "sh"
}}

Replace <code><username></code> with your SF user name. Set up a special git-svn branch for FGAddon gatekeeping and dcommitting changes back to the repository:
<syntaxhighlight lang="bash">
$ git branch fgaddon remotes/git-svn
$ git checkout fgaddon
</syntaxhighlight>

And pull in the <code>ornithopter</code> from FGAddon:
<syntaxhighlight lang="bash">
$ git svn rebase
</syntaxhighlight>

To see the current local git-svn repository setup, type:
<syntaxhighlight lang="bash">
$ git branch -vva
$ git remote -v
$ git svn info
</syntaxhighlight>

Then return to the master branch:
<syntaxhighlight lang="bash">
$ git checkout master
</syntaxhighlight>

Finally, set up the remote git repository as a remote:
{{#tag:syntaxhighlight|
$ {{sourceforge url|cmd=git remote add|opt=origin|protocol=ssh|login=<username>|user=<username>|type=git|repo=code-ornithopter}}
| lang = "sh"
}}

And send the master branch to the remote git repository:
<syntaxhighlight lang="bash">
$ git push -u origin master
</syntaxhighlight>

To see the new set up:
<syntaxhighlight lang="bash">
$ git branch -vva
$ git remote -v
</syntaxhighlight>

The repository will be located at {{#tag:span|{{#tag:tt|{{#tag:nowiki|{{sourceforge url|user=<username>|repo=code-ornithopter|branch=master}}}}}}| style="color: blue"}}. Note that the git-svn information stored in the <code>.git/svn</code> directory will not be pushed to remote SoureForge repository, and therefore the link back to FGAddon will only be present in the local copy of the team leader. The git-svn link can be re-established at a later point if necessary.

===== Team setup =====

Set up a [[#Development teams|dedicated development team and grant them access to the git-svn repository]].

===== Pushing to FGAddon =====

Committing to FGAddon is for the local git repository of the team leader. History must be linear in the fgaddon branch, so cherry-picking is the way to go. This is from the [[#Individual developer (git-svn)|Individual developer (git-svn)]] section. In the local git repository, switch to the <code>fgaddon</code> branch:
<syntaxhighlight lang="bash">
git checkout fgaddon
</syntaxhighlight>

Pull in any changes which have occurred in FGAddon:
<syntaxhighlight lang="bash">
git svn rebase
</syntaxhighlight>

To see the commits in the <code>master</code> branch which are not in the <code>fgaddon</code> branch, type one of:
<syntaxhighlight lang="bash">
git log HEAD..master
git log HEAD..master --pretty=oneline
</syntaxhighlight>

Manually select the commits to be sent to FGAddon and cherry-pick them:
<syntaxhighlight lang="bash">
git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...
</syntaxhighlight>

Or to cherry-pick a range of commits:
<syntaxhighlight lang="bash">
git cherry-pick <commit hash 1>^..<commit hash 8>
</syntaxhighlight>

Then check what is to be sent:
<syntaxhighlight lang="bash">
git log git-svn..HEAD
git diff git-svn..HEAD
</syntaxhighlight>

Send the changes to FGAddon, send the git <code>fgaddon</code> branch changes to the remote git repository, and switch back to the master branch:
<syntaxhighlight lang="bash">
git svn dcommit
git push
git checkout master
</syntaxhighlight>

Finally merge in the git svn commits with their new hashes from the <code>fgaddon</code> branch, and send it to the remote git repository:
<syntaxhighlight lang="bash">
git merge fgaddon
git push
</syntaxhighlight>

==== Team members ====

===== Working with the repository =====

Each team member should make a clone of the private git repository:
{{#tag:syntaxhighlight|
$ {{sourceforge source|cmd=git clone|protocol=ssh|login=<username>|user=<username_leader>|type=git|repo=code-ornithopter|post=ornithopter|full=1}}
| lang = "sh"
}}

Replace <code><username></code> with your SourceForge user name, and <code><username_leader></code> is the SourceForge user name of the team leader.

===== Forking and merge requests =====

Alternatively, each team member can fork the git repository under your SourceForge account:
* Go to {{#tag:span|{{#tag:tt|{{#tag:nowiki|{{sourceforge source|user=<username>|repo=code-ornithopter|branch=master|full=1}}}}}}| style="color: blue"}}, where <code><username></code> is the SourceForge user name of the team leader.
* Click on <code>Fork</code>.
* Set the mount point to <code>code-ornithopter</code> and change the label as you wish.

Develop and push to your fork, then make merge requests by clicking on the <code>Request Merge</code> button.

== References ==
<references/>

[[Category:FlightGear]]
[[ca:FGAddon]]
[[de:FGAddon]]
[[fr:FGAddon]]
[[nl:FGAddon]]
[[pl:FGAddon]]

FlightGear wiki:Village pump

2025-12-25T18:06:16Z

Rominet: /* Beware of shortened Git commit IDs */ Add Git command for finding full commit IDs corresponding to shortened ones

FlightGear wiki:Village pump

2025-12-25T11:08:50Z

Rominet: /* Beware of shortened Git commit IDs */

__NEWSECTIONLINK__
{{Archives|[[/Archive 2012|2012]]|[[/Archive 2013|2013]]|[[/Archive 2014|2014]]|[[/Archive 2015|2015]]|[[/Archive 2016|2016]]|[[/Archive 2017|2017]]|[[/Archive 2018|2018]]|[[/Archive 2019|2019]]|[[/Archive 2020|2020]]|[[/Archive 2021|2021]]|[[/Archive 2022|2022]]}}
{{shortcut|FGW:VP}}

Welcome to the '''Village Pump'''. This page is used to discuss the technical issues, operations and guidelines of the [[FlightGear wiki]].

Please [{{fullurl:{{FULLPAGENAME}}|action=edit&section=new}} add new topics] to the '''bottom''' of this page.

Old discussions should be moved to a [[FlightGear wiki:Village pump/Archive YEAR]]. These discussions can then be moved to a relevant talk page if appropriate.

__TOC__

== MediaWiki updated to 1.39.6 ==

We have updated MediaWiki to its latest LTS version 1.39.6 today. Although we've tested the update, chances are that we've missed certain scenarios or features. Please report any issues that you may encounter.

[[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 09:31, 30 January 2024 (UTC)

== Embedded YouTube videos broken ==

It seems that the [[mw:Extension:EmbedVideo|EmbedVideo extension]] was removed at some point. Consequently, pages such as [[Howto:Creating FlightGear Promo Videos]] are broken. At present, the best replacements seems to be [[mw:Extension:EmbedVideo_(fork)|a fork]] and [[mw:Extension:YouTube|Extension:YouTube]].

—'''''[[User:Red Leader|Red Leader]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 19:21, 30 January 2024 (UTC)

: Hi,
: Thanks for the report. It was introduced by today's update, but should be fixed now.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 21:21, 30 January 2024 (UTC)

:: Confirmed, thanks. And I’d completely forgotten about {{[[Template:Wikipedia|wikipedia]]}}. 😅
:: '''''[[User:Red Leader|Red Leader]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 21:57, 30 January 2024 (UTC)

== Forum registration problem ==

Hello,
I would like to register on the forum, but I tried several times without success. I sent an email to the administrator some time ago, but it seems to have been lost. I don't know what to do, is there somebody here who could help? Please tell me if you need additional information.
Thanks very much in advance. [[User:Kestrel|Kestrel]] ([[User talk:Kestrel|talk]]) 13:14, 25 March 2024 (UTC)

: Hi,
: That's unfortunate! You can find my email address at https://forum.flightgear.org/contact.php Please try again if you've done that before, I'll actively monitor the address for any incoming messages, and let me know if you don't get a reply.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 15:01, 25 March 2024 (UTC) (forum admin)

== Sidebar link for "Build server" is broken ==

Hello,

Just wanted to bring to someones attention that the URL for "Build server" currently 404s. Not sure if this resource still exists or if its URL has changed.

Cheers!
-Joshua

: Hi Joshua,
: The URL is still correct, but the build server is temporarily down due to a server failure. It's being worked on, so should be back up "soon".
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 12:29, 3 September 2024 (UTC)

== FlightGear Wikipedia article image needs correctly sourced Flightgear wiki screenshot ==
https://en.wikipedia.org/wiki/FlightGear

The image used for the Flightgear Wikipedia article appears to have been deleted, because it was sourced from the following Flightgear-wiki screenshot page:

[[:File:Bo 105 over Sint Marteen.png]]

which referred to an imgur link instead of the following thread, which gives a CC license based on a google search of the file name:

https://forum.flightgear.org/viewtopic.php?f=88&t=32163&start=0

Discussion on Wikipedia:

https://en.wikipedia.org/wiki/Wikipedia:Files_for_discussion/2024_December_7#File:FlightGear_Flight_Sim_Bo_105_over_Sint_Marteen.png

> ''Subsequent comments should be made on the appropriate discussion page (such as the file's talk page or in a [https://en.wikipedia.org/wiki/Wikipedia:Deletion_review deletion review]).''

The person who uploaded it, or someone from the wiki, should ideally fix the FlightGear wiki page, and do a deletion review for the Wikipedia file. The file may have been used in multiple pages since screenshots are uncommon on Wikipedia due to proprietary apps. Feel free to remove this comment once it's taken care of. Good luck

== Issues with three templates ==

Hi,

The [[Template:Fgmeta_commit|fgmeta commit]] template appears to be broken. It used to work in the first ''Note'' [[Scripted_Compilation_on_Linux_Debian/Ubuntu#For_the_curious:_the_SSH_way|here]] (see the URL).

Also, I tried to use [[Template:Repo_link#Site:_Generic]] to create a link to the [https://gitlab.kitware.com/cmake/cmake.git CMake repo], but didn't manage: IIRC, the link text was empty.

Finally, [[Template:Fgmeta_source]] doesn't seem to to what the doc. says for ''simplepath'': with
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| simplepath = 1
}}</nowiki></pre>

the link text starts with a slash, so I used
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| text = download_and_compile.sh
}}</nowiki></pre>
which is of course more redundant.

Thanks for considering! :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: Good catch. I need to look into that one. I may not have coded the commit part of GitLab into the master {{tl|repo_link}} template.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:41, 13 March 2025 (UTC)

:: All fixed. It was quite simple - the {{tl|fgmeta_source}} template was missing the <code>proj</code> parameter. I've also fixed {{tl|fgmeta_clone}}.

:: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:53, 13 March 2025 (UTC)

::: Thanks for the reply and fixes, Bugman! (And sorry for the delay, I didn't see any notification...) I see the first item is indeed addressed. Regarding the second item, well, I see no place where I'd really want to use this now on the d&c page, so didn't test it. As for the third one, I still get <code>/download_and_compile.sh</code> in the Preview when I try the above {{tl|fgmeta_source}} snippet with <code>simplepath = 1</code>.

::: I looked at {{tl|fgmeta_clone}} too; it looks nice but seems to default to the <code>git://</code> protocol. Would it be possible to make it default to using <code>https://</code>? Thanks again. :-)

::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

:::: Not a problem. For the <code>simplepath</code> parameter, that is the designed behaviour in the {{tl|repo link}} template. In most cases our repositories have complex directory structures and the desired output is the absolute file path, removing the protocol and URL parts of the path. Do you wish to simply have the file name there? No one had asked for that before, so I never added an option for that. In the case of the source repositories, you often want to remove the first part of the absolute path so that for example in SimGear, {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}}</nowiki>) would be shown as {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}}</nowiki>. This is not scriptable in MediaWiki so I left it all for the text parameter.

:::: For the protocol, I have now added the <code>protocol</code> parameter. E.g. <nowiki>{{fgmeta clone | protocol = https}}</nowiki>. That will give <code>{{fgmeta clone | protocol = https}}</code> (as of today generated as <code><nowiki>git clone https://gitlab.com/flightgear/fgmeta.git</nowiki></code>).

:::: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 08:51, 24 March 2025 (UTC)

::::: Thanks Bugman, I've updated the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] to use <code><nowiki>{{fgmeta clone | protocol = https}}</nowiki></code> as you proposed; it works great. For the link to download_and_compile.sh, I can continue to use <code><nowiki>{{fgmeta source | path = download_and_compile.sh | text = download_and_compile.sh}}</nowiki></code>, no problem.

::::: As far as I'm concerned, everything is resolved here, so this thread/section can be deleted if someone wants to “clean up”.

::::: ''Other subject:'' the only remaining thing is that I didn't receive any notification, neither for your replies here nor for the January changes by [[User:Jebba|Jebba]] to the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] that is on my watchlist. I used to receive email notifications for these things years ago, haven't changed my preferences regarding this and don't see any setting that would explain why I don't receive these notifications anymore. Maybe email sending by the wiki software is not quite well configured according to current standards (SPF, DKIM, DMARC)?

::::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Improve the 'simgear clone', 'flightgear clone' and 'fgdata clone' templates ==

Hi,

In order to improve [[Fedora_Packages_and_Compiling]], it would be nice to have the <code><nowiki>{{simgear clone}}</nowiki></code>, <code><nowiki>{{flightgear clone}}</nowiki></code> and <code><nowiki>{{fgdata clone}}</nowiki></code> templates on par with <code><nowiki>{{fgmeta clone}}</nowiki></code> (support for the <code>protocol</code> parameter, etc.). I tried

<nowiki>{{simgear clone | protocol = https | opt = --single-branch --branch release/2024.1 | post = simgear}}</nowiki>

but it doesn't seem to work, as the preview shows this:

<nowiki>git clone --single-branch --branch release/2024.1 git://gitlab.com simgear</nowiki>

(ditto with <code>flightear clone</code> and <code>fgdata clone</code>). Thanks in advance :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: I needed a while to work out the best strategy for these changes. I've now gone through all of the {{tl|repo link}} cloning subtemplates listed on {{tl|repo link/doc related}} and added the <code>project</code> parameter to the templates and the optional <code>protocol</code> parameter. These changes were required as the <code>gl</code> section of the {{tl|repo_link}} template is constructed differently to the <code>sf</code> section. I've also updated the git cloning documentation {{tl|repo link/doc git clone}}. I hope this covers everything you need.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 07:48, 1 April 2025 (UTC)

:: Thanks a lot, Bugman, this works great! Your changes allowed me to perform [https://wiki.flightgear.org/w/index.php?title=Fedora_Packages_and_Compiling&type=revision&diff=141687&oldid=141513 this edit] in [[Fedora_Packages_and_Compiling]]. The only remaining <code>git clone</code> command written in full on that page is for FG's fork of OpenSceneGraph at GitLab. I understand that choosing a proper name for an applicable <code><nowiki>{{... clone}}</nowiki></code> template probably requires some careful thinking... ;-)

:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Default text in Template:Repo link ==

Hi,

The default ''text'' in {{tl|Repo link}} gives somewhat pleasant link texts such as
flightgear/flightgear/src/Scripting/NasalSys.cxx
when the ''site'' is <code>sourceforge</code>, however the result looks like a bug for other sites (though I understand this may be as intended). To be clear, the URLs are correct but the default link texts look weird because they start with the unqualified site name rather than the fully-qualified domain name. For instance,
{{obr}}fgmeta source{{cbr}}
yields [https://gitlab.com/flightgear/fgmeta gitlab/flightgear/fgmeta/next] rather than [https://gitlab.com/flightgear/fgmeta gitlab.com/flightgear/fgmeta/next]. I suggest to replace <code>gitlab</code> with <code>gitlab.com</code> in the default text (where the HTML comment says “Site advertising”) and do the same for <code>github</code>.

Note: the Gitorious web site doesn't exist anymore, maybe that should be removed from the template?

Thanks for considering; I can do the replacement if you wish.

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 10:38, 12 November 2025 (UTC)

: Sounds sensible, so please go ahead!
: Regarding Gitorious, it may be nice to link to an archived version of the repos, such as https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://gitorious.org/flightgear/fgdata.git&visit_type=git Altough this only makes sense for repos or branches that are not part of our current GitLab...
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 13:58, 12 November 2025 (UTC)

:: [https://wiki.flightgear.org/w/index.php?title=Template:Repo_link&action=history Done], thanks Gijs!
::

:: One should be careful using this, though, because the resulting link ''texts'' may be non-existing URLs (after prepending the protocol) despite looking like valid ones, as shown by the first example in [[User:Rominet/Sandbox#FGMeta-Python repo templates]]!

:: So, to avoid people getting trapped by this, maybe the default link text should start with something like <code>[GitLab]/...</code> rather than the <code>gitlab.com/...</code> I just put (to make it clear that such link texts are not supposed to be “Internet addresses”).
:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 16:20, 12 November 2025 (UTC)

::: This is now implemented. For instance, <code>{{obr}}fgmeta-python source {{!}} path = pyproject.toml {{!}} tag = 1.0.0b1 {{cbr}}</code> results in {{fgmeta-python source | path = pyproject.toml | tag = 1.0.0b1 }}. This also holds for GitHub and GitoriousIsNowClosed. SourceForge has no such prefix for now (it initially didn't, and editing its part of {{tl|Repo link}} requires a bit more temerity than what I have at the moment :-)).
::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 09:15, 14 November 2025 (UTC)

: That's a good idea. Note for Gitorious - I added this because there are a number of historical documents/pages that refer to developments that occurred on Gitorious which were not migrated to SourceForge. I originally made the Gitorious links work by pointing to the archive by the Internet Archive (see [[Gitorious]]). However that archive has been offline for a few years now. The Internet Archive are storing all the data so it may return one day.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 22:06, 13 November 2025 (UTC)

== Beware of shortened Git commit IDs ==

While fixing broken links due to the {{tl|foo commit}} templates not specifying <code>proj=flightgear</code> (this was implicit with <code>site=sf</code> but isn't with <code>site=gl</code>), I found that URLs at GitLab don't accept the same shortened Git commit IDs as those at SourceForge:
https://sourceforge.net/p/flightgear/fgdata/ci/807062 - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062 - NOK
https://gitlab.com/flightgear/fgdata/-/commit/807062d - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062d0b6f858885547f27325e829c2bf42a12b - OK

As a consequence, there are probably a lot of broken links in the wiki due to shortened commit IDs. Better always use the long ones...

{{Note|Commit ID 807062 in FGData is not ambiguous at the time of this writing.}}
[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 15:45, 3 December 2025 (UTC)

: I have modified {{tl|Simgear_commit}}, {{tl|Flightgear_commit}}, {{tl|Fgdata_commit}}, etc. (12 templates!) to show a commit ID truncated to 7 characters in the automatically generated link text, so there is no excuse for not using the full commit IDs anymore when using these templates (see the result [[Howto:Building_FlightGear_without_HiDPI_support#Commits|here]] for instance). Thanks to [[User:Gijs|Gijs]] for installing [https://en.wikipedia.org/wiki/Module:Ustring Module:Ustring] which made this possible!

: Note that manually provided ''text'' arguments are not truncated.

: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 10:10, 25 December 2025 (UTC)

Nasal library/geo

2025-12-25T10:37:49Z

Rominet: Fix broken links due to the use of shortened commit IDs (it doesn't work the same way at GitLab as at SourceForge!)

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>geo</code> namespace''' in [[Nasal]]. This namespace provides various geography/position-related [[#Functions|functions]], as well the [[#Coord|main class]]. Everything in the <code>geo</code> namespace is sourced from {{fgdata file|Nasal/geo.nas}}

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Classes ==
=== Coord ===
{{Nasal doc
|mode = class
|text = The main class, used widely for storing and managing positional data. Coordinates may be stored in either {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z) or {{wikipedia|geodetic coordinates}} (latitude, longitude, and altitude). In addition, it will convert coordinates as necessary. However, note that for the conversion to work, set_latlon() and set_xyz() must be used.
}}
==== new() ====
{{Nasal doc
|syntax = geo.Coord.new([coord]);
|text = Constructor function. Returns a new <code>geo.Coord</code> instance.
|param1 = coord
|param1text = An optional <code>geo.Coord</code> instance. If given, the returned instance will contain the values from this argument.
|example1 = var coord = geo.Coord.new();
|example2 = var ac_pos = geo.aircraft_position();
var coord = geo.Coord.new(ac_pos);
coord.dump();
}}
==== set() ====
{{Nasal doc
|syntax = geo.Coord.set(coord);
|text = Sets the coordinates. Returns the <code>geo.Coord</code> instance.
|param1 = coord
|param1text = Sets the coordinates from another <code>geo.Coord</code> instance.
|example1 = var ac_pos = geo.aircraft_position();
var coord = geo.Coord.new();
coord.set(ac_pos);
coord.dump();
}}
==== set_lat() ====
{{Nasal doc
|syntax = geo.Coord.set_lat(lat);
|text = Sets the {{wikipedia|latitude}} coordinate. Returns the <code>geo.Coord</code> instance.
|param1 = lat
|param1text = The latitude coordinate, in degrees.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(0, 0, 0);
coord.set_lat(45);
coord.dump();
}}
==== set_lon() ====
{{Nasal doc
|syntax = geo.Coord.set_lon(lon);
|text = Sets the {{wikipedia|longitude}} coordinate. Returns the <code>geo.Coord</code> instance.
|param1 = lon
|param1text = The longitude coordinate, in degrees.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(0, 0, 0);
coord.set_lon(90);
coord.dump();
}}
==== set_alt() ====
{{Nasal doc
|syntax = geo.Coord.set_alt(alt);
|text = Sets the {{wikipedia|altitude}} coordinate. Returns the <code>geo.Coord</code> instance.
|param1 = alt
|param1text = The altitude coordinate. Note that this can be in either feet or metres, so make sure you convert correctly. Also note that in conversion, this coordinate will be assumed to be metres above equatorial radius of earth used is that defined by the {{wikipedia|WGS 84}} (6,378,137 metres).
|example1 = var coord = geo.Coord.new();
coord.set_latlon(0, 0, 0);
coord.set_alt(1000);
coord.dump();
}}
==== set_latlon() ====
{{Nasal doc
|syntax = geo.Coord.set_latlon(lat, lon[, alt]);
|text = Sets the latitude and longitude coordinates, and optionally the altitude coordinate. Returns the <code>geo.Coord</code> instance.
|param1 = lat
|param1text = The latitude coordinate, in degrees.
|param2 = lon
|param2text = The longitude coordinate, in degrees.
|param3 = alt
|param3text = The altitude coordinate. Note that this can be in either feet or metres, so make sure you convert correctly. Also note that in conversion, this coordinate will be assumed to be metres above equatorial radius of earth used is that defined by the {{wikipedia|WGS 84}} (6,378,137 metres). Defaults to 0.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(45, 90);
coord.dump();
|example2 = var coord = geo.Coord.new();
coord.set_latlon(45, 90, 1000);
coord.dump();
}}
==== set_x() ====
{{Nasal doc
|syntax = geo.Coord.set_x(x);
|text = Sets the x-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance.
|param1 = x
|param1text = The mandatory x-axis coordinate, in metres.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(0, 0, 0);
coord.set_x(10);
coord.dump();
}}
==== set_y() ====
{{Nasal doc
|syntax = geo.Coord.set_y(y);
|text = Sets the y-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance.
|param1 = y
|param1text = The mandatory y-axis coordinate, in metres.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(0,0,0);
coord.set_y(10);
coord.dump();
}}
==== set_z() ====
{{Nasal doc
|syntax = geo.Coord.set_z(z);
|text = Sets the z-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance.
|param1 = z
|param1text = The mandatory z-axis coordinate, in metres.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(0, 0, 0);
coord.set_y(10);
coord.dump();
}}

==== set_xyz() ====
{{Nasal doc
|syntax = geo.Coord.set_xyz(x, y, z);
|text = Sets all three Cartesian coordinates. Returns the <code>geo.Coord</code> instance. All arguments are mandatory.
|param1 = x
|param1text = The x-axis coordinate, in metres.
|param2 = y
|param2text = The y-axis coordinate, in metres.
|param3 = z
|param3text = The z-axis coordinate, in metres.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
coord.dump();
}}
==== lat() ====
{{Nasal doc
|syntax = geo.Coord.lat();
|text = Returns the latitude coordinate.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(98, 173);
print(coord.lat()); # prints "98"
}}
==== lon() ====
{{Nasal doc
|syntax = geo.Coord.lon();
|text = Returns the longitude coordinate.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(98, 173);
print(coord.lon()); # prints "173"
}}
==== alt() ====
{{Nasal doc
|syntax = geo.Coord.alt();
|text = Returns the altitude coordinate.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(98, 173, 10);
print(coord.alt()); # prints "10"
}}
==== latlon() ====
{{Nasal doc
|syntax = geo.Coord.latlon();
|text = Returns a vector containing the latitude, longitude, and altitude, in that order.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(98, 173, 10);
debug.dump(coord.latlon()); # prints "[98, 173, 10]"
}}
==== x() ====
{{Nasal doc
|syntax = geo.Coord.x();
|text = Returns the x-axis coordinate.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.x()); # prints "10"
}}
==== y() ====
{{Nasal doc
|syntax = geo.Coord.y();
|text = Returns the y-axis coordinate.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.y()); # prints "10"
}}
==== z() ====
{{Nasal doc
|syntax = geo.Coord.z();
|text = Returns the z-axis coordinate.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.z()); # prints "10"
}}
==== xyz() ====
{{Nasal doc
|syntax = geo.Coord.xyz();
|text = Returns a vector containing the x, y, and z coordinates, in that order.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(20, 10, 30);
debug.dump(coord.xyz()); # prints "[20, 10, 30]"
}}
==== is_defined() ====
{{Nasal doc
|syntax = geo.Coord.is_defined();
|text = Returns 1 (true) if all three coordinates (either x/y/z or /lat/lon/alt) are defined. Note that set_latlon() or set_xyz() must be used for this function to work correctly.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.is_defined()); # prints "1"
|example2 = var coord = geo.Coord.new();
print(coord.is_defined()); # prints "0"
}}
==== dump() ====
{{Nasal doc
|syntax = geo.Coord.dump();
|text = Dumps all six coordinates into the console. It requires all three coordinates (either x/y/z or /lat/lon/alt) to be defined. Note that set_latlon() or set_xyz() must be used for this function to work correctly.
|example1 = var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
coord.dump(); # prints "x=10.000000 y=10.000000 z=10.000000 lat=89.981086 lon=44.999998 alt=-6356742.309706"
|example2 = var coord = geo.Coord.new();
coord.set_latlon(90, 45, 10);
coord.dump(); # prints "x=0.055063 y=0.055063 z=6356762.314245 lat=90.000000 lon=45.000000 alt=10.000000"
}}
==== course_to() ====
{{Nasal doc
|syntax = geo.Coord.course_to(coord);
|text = Returns the initial bearing (see [http://www.movable-type.co.uk/scripts/latlong.html#bearing here]) to another <code>geo.Coord</code> instance. The bearing will be an {{wikipedia|absolute bearing}} (in the range 0–360).
|param1 = coord
|param1text = Mandatory <code>geo.Coord</code> instance to calculate bearing to.
|example1 = var c1 = geo.Coord.new();
c1.set_latlon(0, 0);
var c2 = geo.Coord.new();
c2.set_latlon(1, 1);
printf("%.5f", c1.course_to(c2)); # prints "44.99564"
}}

==== distance_to() ====
{{Nasal doc
|syntax = geo.Coord.distance_to(coord);
|text = Returns the great circle distance in metres to another <code>geo.Coord</code> instance. Note that this function ignores altitude.
|param1 = coord
|param1text = Mandatory <code>geo.Coord</code> instance to calculate distance to.
|example1 = var c1 = geo.Coord.new();
c1.set_latlon(0, 0);
var c2 = geo.Coord.new();
c2.set_latlon(1, 1);
printf("%i", c1.distance_to(c2)); # prints "157425"
}}
==== direct_distance_to() ====
{{Nasal doc
|syntax = geo.Coord.direct_distance_to(coord);
|text = Returns the direct distance (cutting through the earth) in metres to another <code>geo.Coord</code> instance.
|param1 = coord
|param1text = Mandatory <code>geo.Coord</code> instance to calculate distance to.
|example1 = var c1 = geo.Coord.new();
c1.set_latlon(0, 0);
var c2 = geo.Coord.new();
c2.set_latlon(45, 90);
printf("%i", c1.direct_distance_to(c2)); # prints "9012522"
}}
==== apply_course_distance() ====
[[File:Missiles on a map.png|thumb]]
{{Nasal doc
|syntax = geo.Coord.apply_course_distance(course, dist);
|text = Calculates a new coordinate from a given course and distancce, and then updates the coordinates to the new set. Returns the <code>geo.Coord</code> instance.
|param1 = course
|param1text = Mandatory absolute bearing (0–360) to use in calculation.
|param2 = dist
|param2text = Mandatory distance in metres to use in calculation.
|example1 = var coord = geo.Coord.new();
coord.set_latlon(0, 0);
coord.dump();
coord.apply_course_distance(245, 10000);
coord.dump(); # lat=-0.037964 lon=-0.081415
|example2 =
# WIP:
# get current aircraft position:
var centerPosition = geo.aircraft_position();
# set up a for-loop
# apply a bearing offset
# and distance 10 nm in front of the current position
# foreach position, add an AI model using put_model
}}

=== PositionedSearch ===
{{Nasal doc
|mode = class
|version = 3.0
|commit = {{fgdata commit|a9576e8c8d292360582aa9ca164ee0043e6a5097|t=commit}}
|text = This class can be used to show differences between FGPositioned (namespace: <code>positioned</code>) search queries. Although it is only used for [[MapStructure]] and the [[Nasal Browser]] as of 09/2016, it can also be used for other applications.
}}
==== new() ====
{{Nasal doc
|syntax = geo.PositionedSearch.new(searchCmd, onAdded, onRemoved[, obj]);
|text = Constructor function. Returns a new <code>geo.PositionedSearch</code> instance.
|param1 = searchCmd
|param1text = A mandatory function that will actually do the searching. It must return a vector containing the elements from the search.
|param2 = onAdded
|param2text = A mandatory function that will be called if a element has been added to the search results. The element added will be passed to this function.
|param3 = onRemoved
|param3text = A mandatory function that will be called if a element has been removed from the search results. The element removed will be passed to this function.
|param4 = obj
|param4text = Optional <code>'''me'''</code> reference. This will be used as the <code>'''me'''</code> reference in each of the above fucntions.
|example1 = var searchCmd = func(){
return positioned.findAirportsWithinRange(10);
};

# This function will be called whenever an item is added
var added = func(apt){
print("Airport ", apt.id, " added");
}

# This function will be called whenever an item is removed
var removed = func(apt){
print("Airport ", apt.id, " removed");
}

# Create a new object, passing to it the search function to be used and the callbacks
var searcher = geo.PositionedSearch.new(searchCmd, added, removed);

# Actually update the searcher object
searcher.update();
}}
==== test() ====
{{Nasal doc
|syntax = geo.PositionedSearch.test([from[, to]]);
|text = Performs a test of the class. It benchmark's the amount of time it switch between searches for fixes at certain ranges.
|param1 = from
|param1text = Optional distance parameter in nautical miles for the first search for fixes. Defaults to 640.
|param2 = to
|param2text = Optional distance parameter in nautical miles for the second search for fixes. Defaults to 320.
|example1 = geo.PositionedSearch.test(); # prints the test results and changed elements
|example2 = geo.PositionedSearch.test(10, 50); # prints the test results and changed elements
}}
==== update() ====
{{Nasal doc
|syntax = geo.PositionedSearch.update([searchCmd]);
|text = Performs an search. It executes the search function and analyses the results.
|param1 = searchCmd
|param1text = Optional search function to use instead of the one given in <code>[[#new()_2|PositionedSearch.new()]]</code>.
|example1 = var searchCmd = func(){
return positioned.findAirportsWithinRange(10);
};
var added = func(apt){
print("Airport ", apt.id, " added");
}
var removed = func(apt){
print("Airport ", apt.id, " removed");
}

var searcher = geo.PositionedSearch.new(searchCmd, added, removed);
searcher.update();
}}
==== _equals ====
{{Nasal doc
|syntax = geo.PositionedSearch._equals;
|text = Function that checks if two objects are equal. You must redefine this function to use <code>geo.PositionedSearch</code> for other uses.
|example1 = var searchCmd = func(){
var vec = [];
var max = rand() * 10;
for(var i = 1; i <= max; i += 1){
append(vec, i);
}
return vec;
};
var added = func(num){
print(num, " added");
}
var removed = func(num){
print(num, " removed");
}

var searcher = geo.PositionedSearch.new(searchCmd, added, removed);
searcher._equals = func(a, b){ return a == b; }
searcher.update();
print("====");
searcher.update(); # run again to see differences between both queries
}}

== Functions ==
=== aircraft_position() ===
{{Nasal doc
|syntax = geo.aircraft_position();
|text = Returns the main aircraft's current position in the form of a <code>geo.Coord</code> object. Note that the altitude will be in metres.
|example1 = var ac_pos = geo.aircraft_position();
ac_pos.dump();
}}

=== click_position() ===
{{Nasal doc
|syntax = geo.click_position();
|text = Returns the position of the last mouse click on the landscape. Note that the altitude will be in metres.
|example1 = var click_pos = geo.click_position();
click_pos.dump();
}}

=== elevation() ===
{{Nasal doc
|syntax = geo.elevation(lat, lon[, max_alt]);
|text = Returns the elevation in metres of a certain point on the scenery. See also {{func link|geodinfo()}} (which is used internally).

If the terrain altitude has not yet been loaded in the area identified by the coordinates, the function returns the ''nil'' value.
|param1 = lat
|param1text = Mandatory latitude coordinate.
|param2 = lon
|param2text = Mandatory longitude coordinate.
|param3 = max_alt
|param3text = Optional altitude in metres from which to begin searching. Defaults to 10,000 m.
|example1 = var ac_pos = geo.aircraft_position();
var elev = geo.elevation(ac_pos.lat(), ac_pos.lon());
printf("Terrain elevation: %i m", elev);
}}

=== format() ===
{{Nasal doc
|syntax = geo.format(lat, lon);
|text = Returns the coordinate formatted as a string. The format will be the same as used for scenery tiles, e.g., <code>w010n50</code> (10 degrees West, 50 degrees North).
|param1 = lat
|param1text = Mandatory latitude coordinate.
|param2 = lon
|param2text = Mandatory longitude coordinate.
|example1 = var ac_pos = geo.aircraft_position();
print(geo.format(ac_pos.lat(), ac_pos.lon()));
}}

=== normdeg() ===
{{Nasal doc
|syntax = geo.normdeg(angle);
|text = Normalizes an angle to be in the range 0–360.
|param1 = angle
|param1text = Mandatory angle to normalize.
|example1 = print(geo.normdeg(45)); # print "45"
|example2 = print(geo.normdeg(-90)); # print "270"
|example3 = print(geo.normdeg(1060)); # print "340"
|example4 = print(geo.normdeg(-653)); # print "67"
}}

=== normdeg180() ===
{{Nasal doc
|syntax = geo.normdeg180(angle);
|version = 2.12
|commit = {{fgdata commit|8c23d095b05c3ba2d9592375b0c2854e2cbcd180|t=commit}}
|text = Normalizes an angle to be in the range -180–180.
|param1 = angle
|param1text = Mandatory angle to normalize.
|example1 = print(geo.normdeg180(96)); # print "96"
|example2 = print(geo.normdeg180(-96)); # print "-96"
|example3 = print(geo.normdeg180(256)); # print "-104"
|example4 = print(geo.normdeg180(-209)); # print "151"
}}

=== put_model() ===
{{Nasal doc
|syntax = geo.put_model(path, lat, lon[, elev[, hdg[, pitch[, roll]]]]);
geo.put_model(path, coord[, hdg[, pitch[, roll]]]]);
|text = Places a model in the simulation at a given location and orientation. If successful, returns the model's root property as a <code>props.Node</code> object.
|param1 = path
|param1text = Path to the model as a string.
|param2 = lat
|param2text = Latitude coordinate.
|param3 = lon
|param3text = Longitude coordinate.
|param4 = elev
|param4text = Optional altitude. Defaults to <code>'''nil'''</code>, in which case the model will be placed on the terrain. Note that an error will be thrown if the terrain's elevation cannot be found, e.g., if there is no scenery tile loaded at the location.
|param5 = coord
|param5text = A <code>geo.Coord</code> instance, which, if given, replaces '''lat''', '''lon''' and '''elev'''.
|param6 = hdg
|param6text = Optional model heading. Defaults to 0.
|param7 = pitch
|param7text = Optional model pitch. Defaults to 0.
|param8 = roll
|param8text = Optional model roll. Defaults to 0.
|example1 = var path = 'Models/Geometry/glider.ac';
var coord = geo.aircraft_position();
var course = getprop("/orientation/heading-deg");
coord.apply_course_distance(course, 100); # Model to be added 100 m ahead
var model = geo.put_model(path, coord, course); # Place the default glider
|example2 = var path = 'Models/Geometry/glider.ac';
var coord = geo.aircraft_position();
coord.apply_course_distance(getprop("/orientation/heading-deg"), 100); # model to be added 100 m ahead
var model = geo.put_model(path, coord.lat(), coord.lon(), coord.alt(), 0, 45, 50); # Place the default glider
}}

=== tile_index() ===
{{Nasal doc
|syntax = geo.tile_index(lat, lon);
|text = Returns the current tile's index. Effectively a wrapper for {{func link|tileIndex()}}.
|param1 = lat
|param1text = Mandatory latitude coordinate.
|param2 = lon
|param2text = Mandatory longitude coordinate.
|example1 = var ac_pos = geo.aircraft_position();
print(geo.tile_index(ac_pos.lat(), ac_pos.lon())); # prints the index of the current tile
}}

=== tile_path() ===
{{Nasal doc
|syntax = geo.tile_path(lat, lon);
|text = Returns the current tile's path under <tt>''[[$FG_SCENERY]]/Terrain''</tt>.
|param1 = lat
|param1text = Mandatory latitude coordinate.
|param2 = lon
|param2text = Mandatory longitude coordinate.
|example1 = var ac_pos = geo.aircraft_position();
printfinddata(geo.tile_path(ac_pos.lat(), ac_pos.lon())); # prints the path of the current
}}

=== viewer_position() ===
{{Nasal doc
|syntax = geo.viewer_position();
|text = Returns the current viewer position in the form of a <code>geo.Coord</code> object. Note that the altitude will be in metres.
|example1 = var v_pos = geo.viewer_position();
v_pos.dump();
}}

== Variable ==
=== ERAD ===
{{Nasal doc
|syntax = geo.ERAD;
|text = Radius of Earth in metres. This is almost equivalent to Earth's equatorial radius (6,378,137 m). Value: 6,378,138.12
}}

{{Nasal namespaces}}

Nasal library/io

2025-12-25T10:34:38Z

Rominet: Fix broken links due to the use of shortened commit IDs (it doesn't work the same way at GitLab as at SourceForge!)

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>io</code> namespace''' in [[Nasal]]. This namespace provides APIs for input/output (IO) operations on files. The <code>io</code> namespace is sourced from {{fgdata file|Nasal/io.nas}} and {{simgear file|simgear/nasal/iolib.c}}.

== Functions ==
=== basename() ===
{{Nasal doc
|syntax = io.basename(path);
|version = 3.0
|commit = {{fgdata commit|6ae3fae39397fca5a2f5d6fba0bb2e659a7edc8b|t=commit}}
|text = Returns last element of a path as a string.
|param1 = path
|param1text = Path as a string.
|example1 = var path = '/demo/demo.xml';
print(io.basename(path)); # prints "demo.xml"
|example2 = var path = 'C:\FlightGear\FlightGear 3.2.0\data';
print(io.basename(path)); # prints "data"
}}

=== close() ===
{{Nasal doc
|syntax = io.close(file);
|text = Flushes and closes the specified file. Returns <code>'''nil'''</code>.
|param1 = file
|param1text = File object as returned by {{func link|open()|page=this}}.
|example1 = var path = getprop("/sim/fg-root") ~ '/keyboard.xml';
var file = io.open(path);
print(io.readln(file)); # prints the XML header
io.close(file);
}}

=== dirname() ===
{{Nasal doc
|syntax = io.dirname(path);
|version = 3.0
|commit = {{fgdata commit|6ae3fae39397fca5a2f5d6fba0bb2e659a7edc8b|t=commit}}
|text = Returns the directory of a path as a string.
|param1 = path
|param1text = Path as a string.
|example1 = var path = '/demo/demo.xml';
print(io.dirname(path)); # prints "/demo/"
|example2 = var path = 'C:\FlightGear\FlightGear 3.2.0\data';
print(io.dirname(path)); # prints "C:/FlightGear/FlightGear 3.2.0/"
}}

=== flush() ===
{{Nasal doc
|syntax = io.flush(file);
|text = Flushes the file's buffer. This means that the contents of the buffer (a kind of temporary storage) are written to the actual file on the hard disk. Note that the buffer is also flushed when {{func link|close()|page=this}} is called.
|param1 = file
|param1text = File object as returned by {{func link|open()|page=this}}.
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt';
var file = io.open(path, "w"); # create and open file
io.write(file, "Hello, World!"); # write (to the buffer)

var file2 = io.open(path); # open the file separatly
var b = bits.buf(13); # create a buffer
io.read(file2, b, 13); # read file
print(b); # prints nothing

io.flush(file); # flush buffer to file
io.read(file2, b, 13); # read file again
print(b); # prints "Hello, World!"

io.close(file); # close
io.close(file2);
}}

=== include() ===
{{Nasal doc
|syntax = io.include(file);
|version = 3.0
|commit = {{fgdata commit|6ae3fae39397fca5a2f5d6fba0bb2e659a7edc8b|t=commit}}
|text = Loads a given Nasal file into where the function is called from.
|param1 = file
|param1text = Path to file as a string. If it is just a filename, it will be assumed that the file is in the same folder as calling script. Otherwise, it will be searched for in the standard FlightGear directories (see [[Resolving Paths]]).
|example1 = io.include("Nasal/geo.nas"); # include the geo namespace
var coord = Coord.new(); # create a new Coord object
coord.set_latlon(0, 0, 2000); # set coordinates
print(coord.alt()); # prints "2000"
}}

=== load_nasal() ===
{{Nasal doc
|syntax = io.load_nasal(file[, module]);
|text = Loads and executes a given Nasal script into a namespace.
|param1 = file
|param1text = Full path to the Nasal file as a string.
|param2 = module
|param2text = Optional name of module to load the script into as a string. If not given, the namespace will be the name of the file.
|example1text = For the examples, first put the below code in to a new file, <tt>''[[$FG_HOME]]/Export/demo.nas''</tt>:
<syntaxhighlight lang="nasal">
var sayHello = func(){
print("Hello, World!");
}
</syntaxhighlight>
|example1 = var file = getprop("/sim/fg-home") ~ '/Export/demo.nas';
io.load_nasal(file); # load into "demo" namespace
demo.sayHello(); # "Hello, World!" will be printed
|example2 = var file = getprop("/sim/fg-home") ~ '/Export/demo.nas';
io.load_nasal(file, "myDemo"); # load into "myDemo" namespace
myDemo.sayHello(); # "Hello, World!" will be printed
}}

=== open() ===
{{Nasal doc
|syntax = io.open(path[, mode]);
|text = Opens the file with the specified mode and returns an <code>iofile</code> ghost object representing the file.
{{{!}} class="wikitable"
! Mode !! Meaning
{{!-}}
{{!}} <code>r</code>
{{!}} Opens a file for input (reading) operations. The file must exist.
{{!-}}
{{!}} <code>w</code>
{{!}} Creates a new file for output (writing) operations. If the file already exists, its contents will be cleared first.
{{!-}}
{{!}} <code>a</code>
{{!}} Opens a file for appending data. The file is created if it does not exist.
{{!-}}
{{!}} <code>r+</code>
{{!}} Open for input and output operations. The file must exist.
{{!-}}
{{!}} <code>w+</code>
{{!}} Creates a new file for input and output operations. If the file already exists, its contents will be cleared first.
{{!-}}
{{!}} <code>a+</code>
{{!}} Opens a file for input and output operations. Output operations will append data to the end of the file. Input operations are affected by {{func link|seek()|page=this}}, but output operations will move the position back to the end of the file. The file is created if it does not exist.
{{!-}}
{{!}} <code>rb</code>
{{!}} Opens a file for input operations, treating it as a binary file. The file must exist. '''Default mode'''.
{{!-}}
{{!}} <code>wb</code>
{{!}} Creates a new file for output operations, treating it as a binary file. If the file already exists, its contents will be cleared first.
{{!-}}
{{!}} <code>ab</code>
{{!}} Opens a file for appending data, treating it as a binary file. The file is created if it does not exist.
{{!-}}
{{!}} <code>r+b</code> ''or'' <code>rb+</code>
{{!}} Open for input and output operations, treating it as a binary file. The file must exist.
{{!-}}
{{!}} <code>w+b</code> ''or'' <code>wb+</code>
{{!}} Creates a new file for input and output operations, treating it as a binary file. If the file already exists, its contents will be cleared first.
{{!-}}
{{!}} <code>a+b</code> ''or'' <code>ab+</code>
{{!}} Opens a file for input and output operations, treating it as a binary file. Output operations will append data to the end of the file. Input operations are affected by {{func link|seek()|page=this}}, but output operations will move the position back to the end of the file. The file is created if it does not exist.
{{!}}}
|param1 = path
|param1text = Full path to the file as a string.
|param2 = mode
|param2text = Optional mode parameter. See the table below. Defaults to "rb".
|example1text = Note that the below example must be run first for the others to work.
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt';
var file = io.open(path, "w"); # open in write mode
var text = 'Hello, World!' ~ "\r";
io.write(file, text);
io.close(file);
|example2 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt';
var file = io.open(path, "r"); # open in read mode
print(io.readln(file)); # prints "Hello, World!"
io.close(file);
|example3 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt';
var file = io.open(path, "a"); # open in append mode
var text = "\n" ~ 'This is line 2';
io.write(file, text);
io.close(file);
}}

=== read() ===
{{Nasal doc
|syntax = io.read(file, buf, len);
|text = Reads a given number of bytes from the given file and places those bytes into the given buffer. The bytes will be read from the position of the position indicator (this can be changed using {{func link|seek()|page=this}}). Failures are thrown as runtime errors. Returns the number of bytes successfully read.
|param1 = file
|param1text = File object as returned by {{func link|open()|page=this}}.
|param2 = buf
|param2text = Buffer to read bytes into. A new buffer can be created using <code>bits.buf(size)</code>. Must not be smaller than '''len'''.
|param3 = len
|param3text = Number of bytes to read as an integer. The position indicator will be advanced by this number of bytes. Must not be greater than the size of '''buf'''.
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas';
var file = io.open(path);
var len = 5;
var buf = bits.buf(len);
io.read(file, buf, len);
print(buf); # prints "# geo"
io.read(file, buf, len);
print(buf); # prints " func"
io.close(file);
}}

=== read_airport_properties() ===
{{Nasal doc
|syntax = io.read_airport_properties(icao, fname[, target]);
|version = 2.4
|commit = {{fgdata commit|d4fb116cd22821de9669fd8b48c49b1a526dd6b5|t=commit}}
|text = Loads an airport-related XML file. Paths will be concatenated in the following form: <tt>''[[$FG_SCENERY]]/Airports/'''''i'''''/'''''c'''''/'''''a'''''/'''''icao'''''.'''''fname'''''.xml''</tt>. Returns the data as a <code>props.Node</code> object or <code>'''nil'''</code> on error. Note that the file ''must'' be in the [[PropertyList XML files|PropertyList]] format, or else the function will fail.
|param1 = icao
|param1text = ICAO code of the airport as a string.
|param2 = fname
|param2text = Filename of the airport data file as a string, e.g., "groundnet", "ils", "jetways", "rwyuse", "threshold", or "twr". See above for its use in the concatenation of the path.
|param3 = target
|param3text = Optional place to put the results in the [[Property Tree]]. May be either a <code>props.Node</code> object pointing to a place in the Property Tree or a property path.
|example1 = var data = io.read_airport_properties("KSFO", "ils"); # the airport might need changing
props.dump(data); # dump data
|example2 = var node = props.globals.getNode("demo", 1);
io.read_airport_properties("KSFO", "ils", node); # the airport might need changing
props.dump(node); # dump data
|example3 = var path = "/demo";
io.read_airport_properties("KSFO", "ils", path); # the airport might need changing
props.dump(props.globals.getNode(path)); # dump data
}}

=== read_properties() ===
{{Nasal doc
|syntax = io.read_properties(path[, target]);
|text = Loads an XML file. Returns the data as a <code>props.Node</code> object on success or <code>'''nil'''</code> on error. Note that the file ''must'' be in the [[PropertyList XML files|PropertyList]] format, or else the function will fail.
|param1 = path
|param1text = Path to the XML file as a string.
|param2 = target
|param2text = Optional place to put the results in the [[Property Tree]]. May be either a <code>props.Node</code> object pointing to a place in the Property Tree or a property path.
|example1 = var path = getprop("/sim/fg-root") ~ '/keyboard.xml';
var data = io.read_properties(path);
props.dump(data); # dump data
|example2 = var path = getprop("/sim/fg-root") ~ '/keyboard.xml';
var node = props.globals.getNode("demo", 1);
io.read_properties(path, node);
props.dump(node); # dump data
|example3 = var path = getprop("/sim/fg-root") ~ '/keyboard.xml';
var node = "/demo";
io.read_properties(path, node);
props.dump(props.globals.getNode(node)); # dump data
}}

=== readfile() ===
{{Nasal doc
|syntax = io.readfile(file);
|text = Reads and returns a complete file as a string. Failures are thrown as runtime errors.
|param1 = file
|param1text = Path to the file as a string.
|example1 = var file = getprop("/sim/fg-root") ~ '/Nasal/math.nas';
file = io.readfile(file);
print(file);
}}

=== readln() ===
{{Nasal doc
|syntax = io.readln(file);
|text = Reads and returns a single line from the file, advancing the position indicator. Accepts different {{wikipedia|newline}} types, including {{abbr|LF|line feed}}, {{abbr|CR|carriage return}}, and CR+LF. Does not include the EOL character(s) in the returned string. End of file or an error is signaled by returning <code>'''nil'''</code>.
|param1 = file
|param1text = File object as returned by {{func link|open()|page=this}}.
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/bits.nas';
var file = io.open(path);
var line = io.readln(file);
print(line); # prints "var bit = [var _ = 1];"
line = io.readln(file);
print(line); # prints "for (var i = 1; i < 32; i += 1)"
}}

=== readxml() ===
{{Nasal doc
|syntax = io.readxml(path[, prefix]);
|text = Reads an XML file from an absolute path and returns it as a <code>props.Node</code> object. All nodes will be of the string type. Also, all attributes will be converted in subnodes with a prefix appended. Returns <code>'''nil'''</code> on error.
|param1 = path
|param1text = Absolute path to the XML file.
|param2 = prefix
|param2text = Optional prefix to give to the attribute nodes. If it is <code>'''nil'''</code>, then attributes will be ignored. Defaults to "___" (three underscores).
|example1text = First, put the following code into <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>:
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<foo>
<bar attr1="Hello" attr2="World">abc</bar>
<bar>xyz</bar>
</foo>
</syntaxhighlight>
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.xml';
var data = io.readxml(path);
props.dump(data); # dump data
}}

=== seek() ===
{{Nasal doc
|syntax = io.seek(file, position, whence);
|text = Moves the pointer position to a specified place.
|param1 = file
|param1text = File object as returned by {{func link|open()|page=this}}.
|param2 = position
|param2text = Number of bytes offset from '''whence''' as an integer. If '''whence''' is {{func link|SEEK_SET|page=this}}, this cannot be negative.
|param3 = whence
|param3text = Specifies position to set the offset from. Must be one of {{func link|SEEK_SET|page=this}} (beginning of file), {{func link|SEEK_END|page=this}} (end of file), or {{func link|SEEK_CUR|page=this}} (current pointer position).
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas';
var file = io.open(path, "r"); # open file
var len = 15;
var buf = bits.buf(len);
io.seek(file, 122, io.SEEK_SET); # set to the desired position
io.read(file, buf, len); # read file
print(buf); # prints "geo.Coord class"
io.close(file); # close file
}}

=== stat() ===
{{Nasal doc
|syntax = io.stat(path);
|text = Calls {{wikipedia|stat (system call)|stat}} and returns a vector containing 12 pieces of data. See the table below for a list of them in order from first in the vector to last. Returns <code>'''nil'''</code> if the file does not exist.
{{{!}} class="wikitable"
! Data !! Meaning
{{!-}}
{{!}} dev {{!!}} Identifier of device containing file
{{!-}}
{{!}} ino {{!!}} Inode number
{{!-}}
{{!}} mode {{!!}} Protection mode
{{!-}}
{{!}} nlink {{!!}} Reference count of hard links
{{!-}}
{{!}} uid {{!!}} User identifier of owner
{{!-}}
{{!}} gid {{!!}} Group identifier of owner
{{!-}}
{{!}} rdev {{!!}} Device identifier (if special file)
{{!-}}
{{!}} size {{!!}} Total file size, in bytes
{{!-}}
{{!}} atime {{!!}} Time of last access as a Unix timestamp
{{!-}}
{{!}} mtime {{!!}} Time of last modification as a Unix timestamp
{{!-}}
{{!}} ctime {{!!}} Time of last status change as a Unix timestamp
{{!-}}
{{!}} type {{!!}} Type of file. May be one of "unk", "reg", "dir", "chr", "blk", "fifo", "lnk", or "sock". See {{simgear file|simgear/nasal/iolib.c|l=214}}.
{{!}}}
|param1 = path
|param1text = Path to the file as a string.
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas';
var stat = io.stat(path);
printf("File size: %s bytes", stat[7]); # prints file size
}}

=== tell() ===
{{Nasal doc
|syntax = io.tell(file);
|text = Returns the current pointer position of the file.
|param1 = file
|param1text = File object as returned by {{func link|open()|page=this}}.
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas';
var file = io.open(path);
io.seek(file, 2, io.SEEK_SET);
print(io.tell(file)); # prints "2"
io.close(file);
}}

=== write() ===
{{Nasal doc
|syntax = io.write(file, string);
|text = Writes a string to a given file and returns the number of bytes successfully written.
|param1 = file
|param1text = File object as returned by {{func link|open()|page=this}}.
|param2 = string
|param2text = String to write to the file.
{{tip|It is good practice to make sure that all lines, including the last one, end in a newline (<code>\n</code>). This will especially help if you will be calling {{func link|readln()|page=this}} on the file later.}}
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt';
var file = io.open(path, "wb"); # open in write mode
var str = 'Hello World!' ~ "\n";
io.write(file, str); # write the data
io.close(file); # close (and flush) the file stream
}}

=== write_properties() ===
{{Nasal doc
|syntax = io.write_properties(path, prop);
|text = Writes nodes from the [[Property Tree]] to an XML file in FlightGear's [[PropertyList XML files|PropertyList]] format. If the file does not exist, it will be created. If it does, all contents will be overwritten. Returns the filename on success or <code>'''nil'''</code> on error.
|param1 = path
|param1text = Path of the file to write to as a string. If it does not have a <tt>.xml</tt> extension, <tt>.xml</tt> will be added to it.
|param2 = prop
|param2text = Either a property path or a <code>props.Node</code> object. Note that, when the latter is used, results will be more accurate if it refers to a node in the Property Tree, otherwise the node will have to be copied, which may change the node type.
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.xml';
var prop = "/position";
print(io.write_properties(path, prop));
|example2 = var path = getprop("/sim/fg-home") ~ '/Export/demo.xml';
var prop = props.globals.getNode("position");
print(io.write_properties(path, prop));
|example3 = var path = getprop("/sim/fg-home") ~ '/Export/demo.xml';
var tree = {
"a": 12.34,
"b": "Hello, World!",
"c": {
"d": [1, 2, 3]
}
};
var prop = props.Node.new(tree);
print(io.write_properties(path, prop));
}}

=== writexml() ===
{{Nasal doc
|syntax = io.basename(path, node[, indent[, prefix]]);
|text = Writes a node structure to an XML file.
|param1 = path
|param1text = Path of the file to write to as a string. If it does not have a <tt>.xml</tt> extension, <tt>.xml</tt> will be added to it.
|param2 = node
|param2text = <code>props.Node</code> object containing the data to write to the file. Attributes should be included as child nodes with a certain '''prefix'''. See also {{func link|readxml()|page=this}}. It must also have just one root node.
|param3 = indent
|param3text = Optional string specifying what characters should be used to indent lines. Defaults to one horizontal tab character (<tt>\t</tt>).
|param4 = prefix
|param4text = Optional string specifying what prefixes attributes will have.
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.xml';
var tree = {
"source": {
___type: "book", # will become an attribute
"title": "The Grand Book of Code",
"author-last": "Echter",
"author-first": "William C.",
"year": "2011",
"publisher": "Pen Publishers",
"city": "Manchester"
}
};
var node = props.Node.new(tree);
io.writexml(path, node);
|example2 = var path = getprop("/sim/fg-home") ~ '/Export/demo.xml';
var tree = {
"source": {
_attr_type: "book",
"title": "The Grand Book of Code",
"author-last": "Echter",
"author-first": "William C.",
"year": "2011",
"publisher": "Pen Publishers",
"city": "Manchester"
}
};
var node = props.Node.new(tree);
io.writexml(path, node, " ", "_attr_"); # indent using two spaces
}}

== Variables ==
=== SEEK_CUR ===
{{Nasal doc
|syntax = io.SEEK_CUR;
|text = Used with {{func link|seek()|page=this}}. Means the offset will be counted from the current pointer postion.
}}
=== SEEK_END ===
{{Nasal doc
|syntax = io.SEEK_END;
|text = Used with {{func link|seek()|page=this}}. Means the offset will be counted from the end of the file.
}}
=== SEEK_SET ===
{{Nasal doc
|syntax = io.SEEK_SET;
|text = Used with {{func link|seek()|page=this}}. Means the offset will be counted from the beginning of the file.
}}

{{Nasal namespaces}}

Highlighting

2025-12-25T10:31:00Z

Rominet: Use full commit ID

== Overview ==

Highlighting is an experimental system on next for highlighting related animated parts of one's aircraft such as the rudder pedals and the rudder, or the undercarriage lever in the cockpit and the undercarriage itself. It also lists the properties that are used in these animations.

The intention is to enable the controls of an aircraft to be explored visually. For example one can find what controls the steering on a 777 by moving the mouse over the nose-wheel; this will highlight the tiller control in the cockpit. In practise it's easier to do this using an Extra View window so that one can see inside the cockpit at the same time as the external aircraft.

== Demo video ==

See: http://op59.net/fg-highlighting-demo.ogv

== Usage ==

See menu '''Help / Highlighting''' which opens the '''Highlighting''' dialogue box with an '''Enabled''' checkbox. When enabled, moving the mouse over an animated part of the aircraft such as a control surface or cockpit control will highlight the animation, plus any related animations. The dialogue box will also show the properties that are involved in the animation and information about related dialogue boxes.

== Details ==

Highlighting currently works best with YASim aircraft - the system gathers information from YASim about associations between properties (e.g. <code>/controls/flight/flaps</code> and <code>/surface-positions/flap-pos-norm</code>). One can gather similar information from JSBSim but this is not yet working properly.

Information is also gathered from autopilot filters (on the 777 these associate <code>/controls/flight/rudder-nul</code> with <code>/fcs/fbw/yaw/rudder-ratio-out</code>).

See: {{flightgear commit|1bafe15c4cc5a05509ee06b50cfe123f6f36ef54}}

Changelog 2016.2

2025-12-25T10:29:21Z

Rominet: Fix broken links due to the use of shortened commit IDs (it doesn't work the same way at GitLab as at SourceForge!)

{{changelogs|prev=2016.1|next=2016.3}}

The FlightGear development team is delighted to announce the v2016.2 "Barcelona" release of FlightGear, the free, open-source flight simulator. This new version contains many exciting new features, enhancements and bugfixes. Highlights in this release include the Space Shuttle, ALS filters, a new HTTP TerraSync system, and improvements to our automatic ATIS.

Founded in 1997, FlightGear is developed by a worldwide group of volunteers, brought together by a shared ambition to create the most realistic flight simulator possible that is free to use, modify and distribute. FlightGear is used all over the world by desktop flight simulator enthusiasts, for research in universities and for interactive exhibits in museums.

FlightGear features more than 400 aircraft, a worldwide scenery database, a multiplayer environment, detailed sky modelling, a flexible and open aircraft modelling system, varied networking options, multiple display support, a powerful scripting language and an open architecture. Best of all, being open-source, the simulator is owned by the community and everyone is encouraged to contribute.

Download FlightGear v2016.2 for free from [http://www.flightgear.org/ FlightGear.org]

FlightGear – Fly Free!

=== Release name ===
In line with the [[release plan]] adopted in FlightGear v2016.1, this release has been named after its default airport, [[Barcelona–El Prat Airport|Barcelona Airport]] (LEBL).

=== Major enhancements in this release ===
==== Core ====
* Video configuration can now be saved.
* The [[TerraSync]] server has been switched to a HTTP-based system instead of SVN.
* All scenery models have been cleaned up and moved to TerraSync.

==== ATIS and METAR ====
* Various improvements in the reporting of wind, atmospheric pressure, and sky cover
* Custom ATIS formats for the US/Canada/Pacific region and the UK based on real recordings
* Bug fixes and data updates to reduce occurrence of NIL weather

==== Atmospheric Light Scattering ====
* Filters have been added, enabling infrared and night-vision views.
* [[ALS technical notes#ALS procedural lights|ALS procedural lights]] have been added.
* An ALS-based system for displaying [[birds]] has been added.

==== Environment Rendering ====
* A bug that prevented precipitation from appearing has been fixed.

==== Multiplayer ====
* A bug in the multiplayer protocol has been {{flightgear commit|4f8cbbb204bd9e28aeed71de8ae0b88019981124|t=fixed}}.

==== Usability ====
* [[Route Manager]] now allows entry of a space-separated list of waypoints.

==== Internationalization ====
* The Italian translation for menus, loading messages and help for command line switches has been updated.

==== Scenery ====
* Further improvements to regional textures.
* New buildings for Heathrow Airport and [[Barcelona–El Prat Airport]]

==== Nasal Scripting ====
* A bug in {{func link|clamp()|math}} has been {{simgear commit|bba11c18d1ebf2c347d6330ff1d5b9aef75e76cb|t=fixed}}.

==== Documentation ====
* A Chinese translation of the Manual has been added.

==== Highlighted new and improved aircraft ====
* [[Parachutist]]
* [[Piper J3 Cub]]
* [[Boeing 757]]
* [[Extra EA-500]]
* [[Saab JA-37 Viggen]]
* [https://forum.flightgear.org/viewtopic.php?f=4&t=28475 Cessna 182S Skylane]
* [[Space Shuttle]]
* [[Beagle Pup]]
* [[Icaro Laminar 13 MRX]]

==== Other ====
===== FGPromo: A FlightGear Promotional Video =====
After more than 5 months of hard work, FGPromo, a video showing off FlightGear at its finest, has been released!
{{#ev:youtube|yPBdJT2Pkdc||center}}

==== Bug fixes ====
* See [https://sourceforge.net/p/flightgear/codetickets/search/?q=%21ticket_num%3A437+AND+status%3AFixed+AND+mod_date%3A%5B2016-02-17T00%3A00%3A00Z+TO+2016-05-17T00%3A00%3A00Z%5D our bugtracker] for a list, albeit incomplete, of the bugs fixed in this release.

[[Category:FlightGear changelogs]]
[[Category:New Versioning Scheme]]

Performance testing by replaying recordings

2025-12-25T10:27:35Z

Rominet: Use full commit ID (which are safer, even though the length was sufficient for GitLab here)

== Overview ==

Continuous recordings can record and replay the main window's size and the view (view type, direction, zoom), so replaying can be used to do standardised performance testing of the rendering code.

We have a Python script in the flightgear repository called {{flightgear file|scripts/python/performance_replay.py}} that replays a recording in Flightgear while gathering frame-time information, from which is outputs statistics such as average and standard deviation frame times and average frame rate.

Recordings can be replayed from a URL, which simplifies various use cases.

As of '''2021-11-8''', these changes have been pushed to next; See: {{flightgear commit|50a4d869617e6dd85ea8db8843f2e3cf99bc6834}}

== Usage ==

Example usage replaying a short recording of the Harrier-GR3 at LOWI, replaying window size and view changes, and then showing frame-rate statistics:

./flightgear/scripts/python/performance_replay.py -f ./run_fgfs.sh -i http://op59.net/harrier-gr3-20211107-162046-continuous.fgtape

== Future ==

* Improve communication - at the moment, the telnet protocol is slow and limits how much data can be transfered, which restricts the amount of data sent from Flightgear to performance_replay.py after replay has finished.
* Specify a fixed set of weather parameters, possibly including a fixed seed for random number generation. Also see [[Advanced_weather#Connection_with_the_multiplayer_system]].
* Write output data to a file so it can be available to other programmes, e.g. for plotting.

== Other ==

* This was worked on in the 2021 Hackathon - see: [[Hackathon_Proposal:_Performance_testing_by_replaying_recordings]]
* For details of the Continuous recording format, see: {{flightgear source|path=docs-mini/README-recordings.md}}

Canvas GUI

2025-12-25T10:24:25Z

Rominet: Fix broken links due to the use of shortened commit IDs (it doesn't work the same way at GitLab as at SourceForge!)

{{Out of date}}
{{Canvas Navigation}}

{{cquote
|<nowiki>I'd love for FlightGear to be runtime configurable through a GUI --
just drag and drop a property onto a drop-down menu, a keyboard
diagram, etc., and build new dialogs while the plane is flying.</nowiki>
|{{cite web |url=http://www.mail-archive.com/flightgear-devel%40flightgear.org/msg09560.html
|title=<nowiki>starting the XML GUI; early implementors needed</nowiki>
|author=<nowiki>David Megginson</nowiki>
|date=<nowiki> Fri, 08 Nov 2002 17:15:38 -0800</nowiki>
}}
}}

{{Note| the GUI API documentation can be found here: [[Canvas GUI API]]}}

== Background ==
{{Mergeto|Howto:Creating a Canvas GUI Widget}}
In order to eventually phase out PUI completely, we need to stop adding PUI dependencies to the source tree. We now have the Canvas system, and there’s a formal decision to modernize the GUI using the Canvas, and completely replace PUI sooner rather than later.

The shortcomings of our GUI, and PUI in particular, have been repeatedly brought up on the devel list over the years.

It was a lot of work to get rid of hard-coded PUI dialogs, and we still have a bunch of hard-coded PUI widgets – as long as we have those, getting totally rid of PUI will be increasingly difficult, because each hard-coded widget will either need to be phased out or manually ported.

Which is exactly the reason why adding additional PUI widgets to the source tree is a really bad idea and counter-constructive to accomplish our long-term goal of phasing out PUI completely.

We should really work out a plan to get rid of hard-coded PUI widgets and re-implement them using canvas-driven widgets, and extend the canvas as we go. Once that is accomplished, completely replacing PUI will become much more straightforward, because it will basically boil down to writing a parser in Nasal to turn our existing dialogs into canvas widgets.

Adding more and more hard-coded PUI widgets to the mix will make our work increasingly difficult, especially if they implement important and useful features that we really want.

We really need to keep the total picture in mind, or we are growing our todo lists with stuff that wasn’t really necessary in the first place.

This discussion is solely focussed on providing a sane migration path, with the ultimate goal of getting totally rid of PUI.

Given that we have agreed to depreciate PUI, there's simply no reasonable reason to keep on adding PUI widgets/dependencies to the source tree - we need to stop doing that right now. Instead, we need to identify required Nasal/Canvas enhancements, in order to allow these widgets to be implemented outside C++ space.

== Status 04/2014 ==
{{Note|As of 04/2014, we have several people independently interested in working on Canvas/GUI features:
* owenpsmith & macnab (via [[Aircraft Generation Wizard]])
* Philosopher working on an [[Interactive Nasal Console]] using Canvas
* kuifje09 working on Canvas/GUI widgets (for [[FGPlot]])
* galvedro & Necolatis working on a Canvas-based procedurally created failure management dialog [[A Failure Management Framework for FlightGear]]
* punkedpanda interested in helping with GUI improvements
* also, one user mentioned being interested in working on an integrated GUI launcher in {{Issue|1295}}
It would make sense to coordinate all these efforts a little, so if you're working on anything related, please get in touch via the Canvas subforum.
}}

{{cquote
|<nowiki>So far, Canvas/MapStructure have helped make 2D maps available for all needs in FlightGear, and a canvas/Nasal-based parser that processes our existing GUI dialogs/HUDs or 2D panels code would have the same benefits (GUI: 10k, HUD:3k, 2D panels:4k). Generic canvas/Nasal framework for each of those would probably also be under 4k in total. But it is so much easier being NOT consistent.</nowiki>
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=209465#p209465
|title=<nowiki>Re: scaling instruments in xml</nowiki>
|author=<nowiki>Hooray</nowiki>
|date=<nowiki>Wed May 14</nowiki>
}}
}}

Before creating new widgets please have a look at Tom's fgdata branch: {{gitorious url|fg|toms-fgdata|branch=canvas-gui-demo}}
Tom is currently working on creating a standard widget and layout system (similar to eg. Qt). At the moment there only exists a button widget (but already with focus, and hover/press effects) [http://forum.flightgear.org/viewtopic.php?f=24&p=186563#p186563].
Specifically, see {{gitorious source|fg|toms-fgdata|branch=canvas-gui-demo|path=Nasal/canvas/gui|view=tree|pre=$FG_ROOT}}.

Before we can replace PUI with a Canvas based GUI a lot work has to be done. Tom is currently working on extending the current canvas windows manager to also become a simple decorator engine which will allow creating unified window decorations and handling like dragging/resizing/closing windows. When this is done we can think of creating simple dialogs. And then we can start creating different widgets and see how to implement a layouting engine. And only then we can start thinking about replacing PUI dialogs with Canvas dialogs. (We may also need a fallback for older hardware as render-to-texture probably won't be supported).

So in the current state it would bring us much benefit to create a separate canvas dialog showing log messages without being able to show it in normal PUI dialogs. Later if we have got a list widgets it will be very easy to just print the log messages to this list widget.

== Creating new Widgets ==

* text label
* checkbox
* radio buttons
* text field
* edit box

== PUI Widgets ==
Canvas dialogs are definitely the way to go, as they are far more flexible and will replace PUI in the future. Since I think FG 2.11 you can create canvas dialogs with window decoration, including a title bar allowing to drag the window around and a close icon:

<syntaxhighlight lang="nasal">
var dlg = canvas.Window.new([400,300], "dialog")
.set("title", "My Canvas Dialog");
</syntaxhighlight>

The existing XML dialogs can still be used and will also be usable in the future (by a backwards compatibility layer or some migration path).

Implementing all our existing PUI/XML-based dialogs is almost certainly going to be more work than providing a Nasal-space migration path/wrapper that reads the old dialogs and turns them into "modern" canvas windows, possibly by just overwriting the dialog-show fgcommand via the new removecommand/addcommand APIs. And phasing out canvas widget should be fairly straightforward too, because those can be directly mapped to embedded/nested canvas textures, so I wouldn't worry too much ...

All standard widgets (textbox, label, radio button, checkbox etc) can be provided by a Nasal parser that turns the existing GUI XML into canvas widgets — our hard-coded widgets however, need to be separately re-implemented. Here's a list of custom, hardcoded, PUI widgets which we will need to re-implement using the Canvas, usually located in {{flightgear file|src/GUI}}:

* {{flightgear file|src/GUI/MapWidget.cxx|t=map widget}} (see [[MapStructure]])
** {{flightgear commit|433af2b51a3bcec7488ac2fbf94b8edfc1e1cb43}} (expose the flight recorder/replay buffers via cppbind)
** {{flightgear commit|11c00afaec8836a5f52bcf8832ff2d50e2f11523}} (add support for helipads from apt.dat 850+)
** {{flightgear commit|6bf47cd248ed388e6a4dd3ffa2d00977b00b62fb}} (MapWidget: make use of the new POI system and display cities on the map. This is meant as a preview.)
** {{flightgear commit|658bda6e40da65c317fd387ed1a2fcf628e7ed1b}} (MapWidget: Show counties and towns as well, depending on the zoom. Some colors added.)
** {{flightgear commit|38a373ba845d2bbea920cbcff90be5dc33040fe5}} (Display AI traffic route in map. Add some helpers so MapWidget can show the origin and destination of AIAircraft with a FlightPlan.)
* {{flightgear file|src/GUI/FGPUIDialog.cxx|l=169|t=loglist}} {{progressbar|70}}
** Required APIs: logbuffer needs to be exposed to Nasal via cppbind
* {{flightgear file|src/GUI/WaypointList.cxx|l=169|t=waypoint list}}
** {{flightgear commit|7afedb1702829b244fcf998391a83833efee7f01}}
** {{flightgear commit|846fd2169832c8938f04386139de746a06e80d4b}}
* {{flightgear file|src/GUI/AirportList.cxx|t=airport list}}
** Required APIs: extended NasalPositioned API
* {{flightgear file|src/GUI/WaypointList.cxx|t=waypoint list}}
** Required APIs: extended NasalPositioned API
* {{flightgear file|src/GUI/property_list.cxx|t=property list}}
* {{flightgear file|src/GUI/PUIFileDialog.cxx|t=file dialog}}
* {{flightgear file|src/GUI/menubar.cxx|t=menubar}} (see [[Howto:Making a Canvas Menubar]])

In order to re-implement these using the Canvas system, we need to identify Nasal APIs that are currently missing, and which need to be provided via the cppbind framework.

This way, C++ developers can concentrate on providing the missing Nasal/C++ hooks, whereas Nasal developers can provide the required widgets.

[[Category:Canvas GUI]]

Nasal library/math

2025-12-25T10:19:10Z

Rominet: Fix broken links due to the use of shortened commit IDs (it doesn't work the same way at GitLab as at SourceForge!)

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>math</code> namespace''' in [[Nasal]]. This namespace provides various mathematical [[#Functions|functions]] and [[#Variables|variables]]. The <code>math</code> namespace is sourced from two files:
* {{simgear file|simgear/nasal/mathlib.c}}
* {{fgdata file|Nasal/math.nas}}

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Functions ==
=== abs() ===
{{Nasal doc
|syntax = math.abs(x);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = x
|param1text = This argument is required and should be a number.
|example1 = print(math.abs(1)); # prints "1"
|example2 = print(math.abs(-1)); # prints "1"
}}

=== acos() ===
{{Nasal doc
|syntax = math.acos(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=196|t=Source}}
|text = Implements the arccosine trigonometric function. Returns an angle in radians from the given ratio.
|param1 = x
|param1text = Mandatory number that should be a ratio in the range -1 ≤ x ≤ 1.
|example1 = var ratio = 1 / 1.414;
print(math.acos(ratio) * R2D); # prints the angle in degrees (approximately 45)
}}

=== asin() ===
{{Nasal doc
|syntax = math.asin(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=187|t=Source}}
|text = Implements the arcsine trigonometric function. Returns an angle in radians from the given ratio.
|param1 = x
|param1text = Mandatory number that should be a ratio in the range -1 ≤ x ≤ 1.
|example1 = var ratio = 1 / 1.414;
print(math.asin(ratio) * R2D); # prints the angle in degrees (approximately 45)
}}

=== atan2() ===
{{Nasal doc
|syntax = math.atan2(y, x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=78|t=Source}}
|text = Implements the {{wikipedia|Atan2|two-argument version}} of the arctangent trigonometric function. Returns an angle in radians between the positive x-axis of a plane and the point given by the coordinates (x, y) on it.
|param1 = y
|param1text = Mandatory y-axis coordinate as a number.
|param2 = x
|param2text = Mandatory x-axis coordinate as a number.
|example1 = var x = 1;
var y = 1;
print(math.atan2(y, x) * R2D); # prints the angle in degrees (45)
|example2 = var x = -1;
var y = -1;
print(math.atan2(y, x) * R2D); # prints the angle in degrees (-135)
}}

=== avg() ===
{{Nasal doc
|syntax = math.avg(x[, y[, z[, ...]]]);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|version = 2.4
|commit = {{fgdata commit|36c48caaf273b0547bc8b54ae1ec8c7f4b9d4151|t=Commit}}
|text = Returns the average of the given numbers. There must be at least one argument, but there may be as many as you like.
|example1 = print(math.avg(1, 2, 3, 4)); # prints 2.5
}}

=== ceil() ===
{{Nasal doc
|syntax = math.ceil(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=97|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3eac382d4d3d709e263f7700350f5ea7523|t=Commit}}
|text = Returns the {{wikipedia|Ceiling function|ceiling}} of a number, that is, the smallest following integer.
|param1 = x
|param1text = Number to return the ceiling of.
|example1 = print(math.ceil(2)); # prints 2
|example2 = print(math.ceil(2.1)); # prints 3
|example3 = print(math.ceil(-2.9)); # prints -2
}}

=== clamp() ===
{{Nasal doc
|syntax = math.clamp(x, min, max);
|source = {{simgear file|simgear/nasal/mathlib.c|l=117|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3eac382d4d3d709e263f7700350f5ea7523|t=Commit}}
|text = Clamps a number so that is within the range given. All arguments are mandatory and must be numbers.
{{Note|Up until FG v2016.2, the clamping algorithm was not correct, meaning that the function will not behave correctly in FlightGear versions below 2016.2. It was fixed by {{simgear commit|bba11c18d1ebf2c347d6330ff1d5b9aef75e76cb}}}}.
|param1 = x
|param1text = The number to be clamped.
|param2 = min
|param2text = Lower limit of the clamping range.
|param3 = max
|param3text = Upper limit of the clamping range.
|example1text = Note that none of these examples will work properly in FlightGear versions below 2016.2.
|example1 = print(math.clamp(5, 1, 10)); # prints 5
|example2 = print(math.clamp(0, 1, 10)); # prints 1
|example3 = print(math.clamp(12, 1, 10)); # prints 10
}}

=== cos() ===
{{Nasal doc
|syntax = math.cos(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=32|t=Source}}
|text = Implements the cosine trigonometric function. Returns a ratio from a given angle in radians.
|param1 = x
|param1text = Mandatory number that should be an angle in radians.
|example1 = var angle = 180 * D2R;
print(math.cos(angle)); # prints the ratio (-1)
}}

=== exp() ===
{{Nasal doc
|syntax = math.exp(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=41|t=Source}}
|text = Returns the value of ''{{wikipedia|E (mathematical constant)|e|noicon=1}}'' raised to the given poweer.
|param1 = x
|param1text = Mandatory number which is the value of the exponent.
|example1 = printf("%.4f", math.exp(2)); # prints 7.3891
}}

=== floor() ===
{{Nasal doc
|syntax = math.floor(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=88|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3eac382d4d3d709e263f7700350f5ea7523|t=Commit}}
|text = Returns the {{wikipedia|Floor function|floor}} of a number, that is, the largest previous integer.
|param1 = x
|param1text = Number to return the floor of.
|example1 = print(math.floor(2)); # prints 2
|example2 = print(math.floor(2.1)); # prints 2
|example3 = print(math.floor(-2.9)); # prints -3
}}

=== fmod() ===
{{Nasal doc
|syntax = math.fmod(x, y);
|source = {{simgear file|simgear/nasal/mathlib.c|l=106|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3eac382d4d3d709e263f7700350f5ea7523|t=Commit}}
|text = Returns the result of the modulo operation of the given numbers, that is, is returns the remainder of '''x''' divided by '''y'''. Unlike {{func link|mod()|page=this}}, this function uses the C library function {{func link|fmod()|link=http://www.cplusplus.com/reference/cmath/fmod/}}, and has different (and more correct) behavior when negative arguments are passed to it (compare example 3 with example 3 of {{func link|mod()|page=this}}). Both arguments are mandatory and must be numbers.
{{Note|This function was initially added <code>math.mod()</code>, but this was overridden by [[#mod.28.29|another version]] which already existed in FGData. In FlightGear 3.0, this function was {{simgear commit|ad83e70cf5983c7b307847aa2cb92c40e42bc534|t=renamed}} to <code>fmod()</code>.}}
|param1 = x
|param1text = The dividend.
|param2 = y
|param2text = The divisor. If this argument is 0, a floating point error will be generated.
|example1 = print(math.fmod(5, 2)); # prints 1 (2 goes into 5 twice with a remainder of 1; 2 * 2 + 1 = 5)
|example2 = print(math.fmod(10, 5)); # prints 0 (5 goes into 10 twice with a remainder of 0; 5 * 2 + 0 = 10)
|example3 = print(math.fmod(-5, 2)); # prints -1 (2 goes into -5 -2 times with a remainder of -1; 2 * -2 + -1 = -5)
}}

=== ln() ===
{{Nasal doc
|syntax = math.ln(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=50|t=Source}}
|text = Returns the natural (base ''e'') logarithm of the given number.
|param1 = x
|param1text = Number to return the logarithm of. Must be greater than 0.
|example1 = printf("%.4f", math.ln(60)); # prints 4.0943
}}

=== log10() ===
{{Nasal doc
|syntax = math.log10(x);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|text = Returns the common (base 10) logarithm of the given number.
|param1 = x
|param1text = Number to return the logarithm of. Must be greater than 0.
|example1 = printf("%g", math.log10(1000)); # prints 3
}}

=== max() ===
{{Nasal doc
|syntax = math.max(x[, y[, z[, ...]]]);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|version = 2.4
|commit = {{fgdata commit|36c48caaf273b0547bc8b54ae1ec8c7f4b9d4151|t=Commit}}
|text = Returns the highest number of the given numbers. There must be at least one argument, but there may be as many as you like.
|example1 = print(math.max(1, 2, 3, 4)); # prints 4
}}

=== min() ===
{{Nasal doc
|syntax = math.min(x[, y[, z[, ...]]]);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|version = 2.4
|commit = {{fgdata commit|36c48caaf273b0547bc8b54ae1ec8c7f4b9d4151|t=Commit}}
|text = Returns the lowest number of the given numbers. There must be at least one argument, but there may be as many as you like.
|example1 = print(math.min(1, 2, 3, 4)); # prints 1
}}

=== mod() ===
{{See also|Nasal library#fmod()}}
{{Nasal doc
|syntax = math.mod(x, y);
|source = {{simgear file|simgear/nasal/mathlib.c|l=106|t=Source}}
|text = Returns the result of the modulo operation of the given numbers, that is, is returns the remainder of '''x''' divided by '''y'''. Note that this function does not not return correct answers when either or both the arguments are negative (see example 3), unlike <code>[[#fmod.28.29|fmod()]]</code>. Both arguments are mandatory and must be numbers.
|param1 = x
|param1text = The dividend.
|param2 = y
|param2text = The divisor. If this argument is 0, infinity will be returned (printed as <code>0e-00</code>).
|example1 = print(math.mod(5, 2)); # prints 1 (2 goes into 5 twice with a remainder of 1; 2 * 2 + 1 = 5)
|example2 = print(math.mod(10, 5)); # prints 0 (5 goes into 10 twice with a remainder of 0; 5 * 2 + 0 = 10)
|example3 = print(math.mod(-5, 4)); # prints 3 (incorrect, should be -1)
}}

=== periodic() ===
{{Nasal doc
|syntax = math.periodic(min, max, x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=130|t=Source}}
|version = 2.10
|commit = {{simgear commit|830bc3eac382d4d3d709e263f7700350f5ea7523|t=Commit}}
|text = Normalizes the given number (e.g., a bearing) to be within a set periodic range (e.g., compass bearings, which go from 0 to 360). All the arguments are mandatory and must be numbers.
|param1 = min
|param1text = Lower boundary of the periodic range.
|param2 = max
|param2text = Upper boundary of the periodic range
|param3 = x
|param3text = Number to normalize.
|example1 = var norm_360 = func(a){
return math.periodic(0, 360, a);
}

print(norm_360(-90)); # prints 270
print(norm_360(45)); # prints 45
|example2 = var norm_180 = func(a){
return math.periodic(-180, 180, a);
}

print(norm_180(45)); # prints 45
print(norm_180(270)); # prints -90
|example3 = print(math.periodic(0, 10, 15)); # prints 5
}}

=== pow() ===
{{Nasal doc
|syntax = math.pow(b, n);
|source = {{simgear file|simgear/nasal/mathlib.c|l=68|t=Source}}
|text = Returns the base '''b''' raised to the '''n''' power. Both arguments are mandatory and must be numbers.
|param1 = b
|param1text = Base.
|param2 = n
|param2text = Exponent.
|example1 = print(math.pow(2, 2)); # prints 4
}}

=== round() ===
{{Nasal doc
|syntax = math.round(x[, p]);
|source = {{simgear file|simgear/nasal/mathlib.c|l=153|t=Source}}
|version = 3.0
|commit = {{simgear commit|ad83e70cf5983c7b307847aa2cb92c40e42bc534|t=Commit}}
|text = Rounds '''x''' to the optional precision ('''p'''). If the fractional part of '''x''' is 0.5, it will always be rounded up. Both argument must be numbers.
|param1 = x
|param1text = Mandatory number to round.
|param2 = p
|param2text = Optional precision to round to. For example, if this is set to 10, '''x''' will be rounded to the nearest 10. Defaults to 1, and should be greater than or equal to 1 for correct output. For rounding to decimal places, it is better to use {{func link|sprintf}}.
|example1 = print(math.round(4.2)); # prints 4
|example2 = print(math.round(4.7)); # prints 5
|example3 = print(math.round(4.5)); # prints 5
|example4 = print(math.round(127, 10)); # prints 130
|example5 = print(math.round(456, 100)); # prints 500
}}

=== sin() ===
{{Nasal doc
|syntax = math.sin(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=23|t=Source}}
|text = Implements the sine trigonometric function. Returns a ratio from a given angle in radians.
|param1 = x
|param1text = Mandatory number that should be an angle in radians.
|example1 = var angle = 90 * D2R;
print(math.sin(angle)); # prints the ratio (1)
}}

=== sgn() ===
{{Nasal doc
|syntax = math.sgn(x);
|source = {{fgdata file|Nasal/math.nas|t=Source}}
|text = Returns the result of the sign function on the given number. If '''x''' is less than 0, -1 one is returned. If '''x''' equals 0, 0 is returned. If '''x''' is greater than 0, 1 is returned.
|param1 = x
|param1text = Mandatory number to return the sign of.
|example1 = print(math.sgn(-6)); # prints -1
|example2 = print(math.sgn(0)); # prints 0
|example3 = print(math.sgn(12)); # prints 1
}}

=== sqrt() ===
{{Nasal doc
|syntax = math.sqrt(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=59|t=Source}}
|text = Returns the square root of the given number.
|param1 = x
|param1text = Mandatory number to return the square root of. Must be greater than or equal to 0.
|example1 = print(math.sqrt(9)); # prints 3
}}

=== tan() ===
{{Nasal doc
|syntax = math.tan(x);
|source = {{simgear file|simgear/nasal/mathlib.c|l=177|t=Source}}
|text = Implements the tangent trigonometric function. Returns a ratio from a given angle in radians.
|param1 = x
|param1text = Mandatory number that should be an angle in radians.
|example1 = var angle = 45 * D2R;
print(math.tan(angle)); # prints the ratio (1)
}}

== Variables ==
=== e ===
{{Nasal doc
|syntax = math.e;
|source = {{simgear file|simgear/nasal/mathlib.c|l=232|t=Source}}
|text = Important mathematical constant (see {{wikipedia|e (mathematical constant)}}). Value in simulation: 2.7182818284590452354
}}
=== pi ===
{{Nasal doc
|syntax = math.pi;
|source = {{simgear file|simgear/nasal/mathlib.c|l=231|t=Source}}
|text = Important mathematical constant (see {{wikipedia|pi (mathematical constant)}}). Value in simulation: 3.14159265358979323846
}}

{{Nasal namespaces}}

FlightGear wiki:Village pump

2025-12-25T10:10:19Z

Rominet: /* Beware of shortened Git commit IDs */ Mention the fact that Foo_commit templates now truncate the commit ID in link text if the latter is automatically generated from the commit ID

__NEWSECTIONLINK__
{{Archives|[[/Archive 2012|2012]]|[[/Archive 2013|2013]]|[[/Archive 2014|2014]]|[[/Archive 2015|2015]]|[[/Archive 2016|2016]]|[[/Archive 2017|2017]]|[[/Archive 2018|2018]]|[[/Archive 2019|2019]]|[[/Archive 2020|2020]]|[[/Archive 2021|2021]]|[[/Archive 2022|2022]]}}
{{shortcut|FGW:VP}}

Welcome to the '''Village Pump'''. This page is used to discuss the technical issues, operations and guidelines of the [[FlightGear wiki]].

Please [{{fullurl:{{FULLPAGENAME}}|action=edit&section=new}} add new topics] to the '''bottom''' of this page.

Old discussions should be moved to a [[FlightGear wiki:Village pump/Archive YEAR]]. These discussions can then be moved to a relevant talk page if appropriate.

__TOC__

== MediaWiki updated to 1.39.6 ==

We have updated MediaWiki to its latest LTS version 1.39.6 today. Although we've tested the update, chances are that we've missed certain scenarios or features. Please report any issues that you may encounter.

[[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 09:31, 30 January 2024 (UTC)

== Embedded YouTube videos broken ==

It seems that the [[mw:Extension:EmbedVideo|EmbedVideo extension]] was removed at some point. Consequently, pages such as [[Howto:Creating FlightGear Promo Videos]] are broken. At present, the best replacements seems to be [[mw:Extension:EmbedVideo_(fork)|a fork]] and [[mw:Extension:YouTube|Extension:YouTube]].

—'''''[[User:Red Leader|Red Leader]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 19:21, 30 January 2024 (UTC)

: Hi,
: Thanks for the report. It was introduced by today's update, but should be fixed now.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 21:21, 30 January 2024 (UTC)

:: Confirmed, thanks. And I’d completely forgotten about {{[[Template:Wikipedia|wikipedia]]}}. 😅
:: '''''[[User:Red Leader|Red Leader]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 21:57, 30 January 2024 (UTC)

== Forum registration problem ==

Hello,
I would like to register on the forum, but I tried several times without success. I sent an email to the administrator some time ago, but it seems to have been lost. I don't know what to do, is there somebody here who could help? Please tell me if you need additional information.
Thanks very much in advance. [[User:Kestrel|Kestrel]] ([[User talk:Kestrel|talk]]) 13:14, 25 March 2024 (UTC)

: Hi,
: That's unfortunate! You can find my email address at https://forum.flightgear.org/contact.php Please try again if you've done that before, I'll actively monitor the address for any incoming messages, and let me know if you don't get a reply.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 15:01, 25 March 2024 (UTC) (forum admin)

== Sidebar link for "Build server" is broken ==

Hello,

Just wanted to bring to someones attention that the URL for "Build server" currently 404s. Not sure if this resource still exists or if its URL has changed.

Cheers!
-Joshua

: Hi Joshua,
: The URL is still correct, but the build server is temporarily down due to a server failure. It's being worked on, so should be back up "soon".
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 12:29, 3 September 2024 (UTC)

== FlightGear Wikipedia article image needs correctly sourced Flightgear wiki screenshot ==
https://en.wikipedia.org/wiki/FlightGear

The image used for the Flightgear Wikipedia article appears to have been deleted, because it was sourced from the following Flightgear-wiki screenshot page:

[[:File:Bo 105 over Sint Marteen.png]]

which referred to an imgur link instead of the following thread, which gives a CC license based on a google search of the file name:

https://forum.flightgear.org/viewtopic.php?f=88&t=32163&start=0

Discussion on Wikipedia:

https://en.wikipedia.org/wiki/Wikipedia:Files_for_discussion/2024_December_7#File:FlightGear_Flight_Sim_Bo_105_over_Sint_Marteen.png

> ''Subsequent comments should be made on the appropriate discussion page (such as the file's talk page or in a [https://en.wikipedia.org/wiki/Wikipedia:Deletion_review deletion review]).''

The person who uploaded it, or someone from the wiki, should ideally fix the FlightGear wiki page, and do a deletion review for the Wikipedia file. The file may have been used in multiple pages since screenshots are uncommon on Wikipedia due to proprietary apps. Feel free to remove this comment once it's taken care of. Good luck

== Issues with three templates ==

Hi,

The [[Template:Fgmeta_commit|fgmeta commit]] template appears to be broken. It used to work in the first ''Note'' [[Scripted_Compilation_on_Linux_Debian/Ubuntu#For_the_curious:_the_SSH_way|here]] (see the URL).

Also, I tried to use [[Template:Repo_link#Site:_Generic]] to create a link to the [https://gitlab.kitware.com/cmake/cmake.git CMake repo], but didn't manage: IIRC, the link text was empty.

Finally, [[Template:Fgmeta_source]] doesn't seem to to what the doc. says for ''simplepath'': with
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| simplepath = 1
}}</nowiki></pre>

the link text starts with a slash, so I used
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| text = download_and_compile.sh
}}</nowiki></pre>
which is of course more redundant.

Thanks for considering! :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: Good catch. I need to look into that one. I may not have coded the commit part of GitLab into the master {{tl|repo_link}} template.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:41, 13 March 2025 (UTC)

:: All fixed. It was quite simple - the {{tl|fgmeta_source}} template was missing the <code>proj</code> parameter. I've also fixed {{tl|fgmeta_clone}}.

:: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:53, 13 March 2025 (UTC)

::: Thanks for the reply and fixes, Bugman! (And sorry for the delay, I didn't see any notification...) I see the first item is indeed addressed. Regarding the second item, well, I see no place where I'd really want to use this now on the d&c page, so didn't test it. As for the third one, I still get <code>/download_and_compile.sh</code> in the Preview when I try the above {{tl|fgmeta_source}} snippet with <code>simplepath = 1</code>.

::: I looked at {{tl|fgmeta_clone}} too; it looks nice but seems to default to the <code>git://</code> protocol. Would it be possible to make it default to using <code>https://</code>? Thanks again. :-)

::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

:::: Not a problem. For the <code>simplepath</code> parameter, that is the designed behaviour in the {{tl|repo link}} template. In most cases our repositories have complex directory structures and the desired output is the absolute file path, removing the protocol and URL parts of the path. Do you wish to simply have the file name there? No one had asked for that before, so I never added an option for that. In the case of the source repositories, you often want to remove the first part of the absolute path so that for example in SimGear, {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}}</nowiki>) would be shown as {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}}</nowiki>. This is not scriptable in MediaWiki so I left it all for the text parameter.

:::: For the protocol, I have now added the <code>protocol</code> parameter. E.g. <nowiki>{{fgmeta clone | protocol = https}}</nowiki>. That will give <code>{{fgmeta clone | protocol = https}}</code> (as of today generated as <code><nowiki>git clone https://gitlab.com/flightgear/fgmeta.git</nowiki></code>).

:::: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 08:51, 24 March 2025 (UTC)

::::: Thanks Bugman, I've updated the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] to use <code><nowiki>{{fgmeta clone | protocol = https}}</nowiki></code> as you proposed; it works great. For the link to download_and_compile.sh, I can continue to use <code><nowiki>{{fgmeta source | path = download_and_compile.sh | text = download_and_compile.sh}}</nowiki></code>, no problem.

::::: As far as I'm concerned, everything is resolved here, so this thread/section can be deleted if someone wants to “clean up”.

::::: ''Other subject:'' the only remaining thing is that I didn't receive any notification, neither for your replies here nor for the January changes by [[User:Jebba|Jebba]] to the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] that is on my watchlist. I used to receive email notifications for these things years ago, haven't changed my preferences regarding this and don't see any setting that would explain why I don't receive these notifications anymore. Maybe email sending by the wiki software is not quite well configured according to current standards (SPF, DKIM, DMARC)?

::::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Improve the 'simgear clone', 'flightgear clone' and 'fgdata clone' templates ==

Hi,

In order to improve [[Fedora_Packages_and_Compiling]], it would be nice to have the <code><nowiki>{{simgear clone}}</nowiki></code>, <code><nowiki>{{flightgear clone}}</nowiki></code> and <code><nowiki>{{fgdata clone}}</nowiki></code> templates on par with <code><nowiki>{{fgmeta clone}}</nowiki></code> (support for the <code>protocol</code> parameter, etc.). I tried

<nowiki>{{simgear clone | protocol = https | opt = --single-branch --branch release/2024.1 | post = simgear}}</nowiki>

but it doesn't seem to work, as the preview shows this:

<nowiki>git clone --single-branch --branch release/2024.1 git://gitlab.com simgear</nowiki>

(ditto with <code>flightear clone</code> and <code>fgdata clone</code>). Thanks in advance :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: I needed a while to work out the best strategy for these changes. I've now gone through all of the {{tl|repo link}} cloning subtemplates listed on {{tl|repo link/doc related}} and added the <code>project</code> parameter to the templates and the optional <code>protocol</code> parameter. These changes were required as the <code>gl</code> section of the {{tl|repo_link}} template is constructed differently to the <code>sf</code> section. I've also updated the git cloning documentation {{tl|repo link/doc git clone}}. I hope this covers everything you need.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 07:48, 1 April 2025 (UTC)

:: Thanks a lot, Bugman, this works great! Your changes allowed me to perform [https://wiki.flightgear.org/w/index.php?title=Fedora_Packages_and_Compiling&type=revision&diff=141687&oldid=141513 this edit] in [[Fedora_Packages_and_Compiling]]. The only remaining <code>git clone</code> command written in full on that page is for FG's fork of OpenSceneGraph at GitLab. I understand that choosing a proper name for an applicable <code><nowiki>{{... clone}}</nowiki></code> template probably requires some careful thinking... ;-)

:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Default text in Template:Repo link ==

Hi,

The default ''text'' in {{tl|Repo link}} gives somewhat pleasant link texts such as
flightgear/flightgear/src/Scripting/NasalSys.cxx
when the ''site'' is <code>sourceforge</code>, however the result looks like a bug for other sites (though I understand this may be as intended). To be clear, the URLs are correct but the default link texts look weird because they start with the unqualified site name rather than the fully-qualified domain name. For instance,
{{obr}}fgmeta source{{cbr}}
yields [https://gitlab.com/flightgear/fgmeta gitlab/flightgear/fgmeta/next] rather than [https://gitlab.com/flightgear/fgmeta gitlab.com/flightgear/fgmeta/next]. I suggest to replace <code>gitlab</code> with <code>gitlab.com</code> in the default text (where the HTML comment says “Site advertising”) and do the same for <code>github</code>.

Note: the Gitorious web site doesn't exist anymore, maybe that should be removed from the template?

Thanks for considering; I can do the replacement if you wish.

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 10:38, 12 November 2025 (UTC)

: Sounds sensible, so please go ahead!
: Regarding Gitorious, it may be nice to link to an archived version of the repos, such as https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://gitorious.org/flightgear/fgdata.git&visit_type=git Altough this only makes sense for repos or branches that are not part of our current GitLab...
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 13:58, 12 November 2025 (UTC)

:: [https://wiki.flightgear.org/w/index.php?title=Template:Repo_link&action=history Done], thanks Gijs!
::

:: One should be careful using this, though, because the resulting link ''texts'' may be non-existing URLs (after prepending the protocol) despite looking like valid ones, as shown by the first example in [[User:Rominet/Sandbox#FGMeta-Python repo templates]]!

:: So, to avoid people getting trapped by this, maybe the default link text should start with something like <code>[GitLab]/...</code> rather than the <code>gitlab.com/...</code> I just put (to make it clear that such link texts are not supposed to be “Internet addresses”).
:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 16:20, 12 November 2025 (UTC)

::: This is now implemented. For instance, <code>{{obr}}fgmeta-python source {{!}} path = pyproject.toml {{!}} tag = 1.0.0b1 {{cbr}}</code> results in {{fgmeta-python source | path = pyproject.toml | tag = 1.0.0b1 }}. This also holds for GitHub and GitoriousIsNowClosed. SourceForge has no such prefix for now (it initially didn't, and editing its part of {{tl|Repo link}} requires a bit more temerity than what I have at the moment :-)).
::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 09:15, 14 November 2025 (UTC)

: That's a good idea. Note for Gitorious - I added this because there are a number of historical documents/pages that refer to developments that occurred on Gitorious which were not migrated to SourceForge. I originally made the Gitorious links work by pointing to the archive by the Internet Archive (see [[Gitorious]]). However that archive has been offline for a few years now. The Internet Archive are storing all the data so it may return one day.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 22:06, 13 November 2025 (UTC)

== Beware of shortened Git commit IDs ==

While fixing broken links due to the {{tl|foo commit}} templates not specifying <code>proj=flightgear</code> (this was implicit with <code>site=sf</code> but isn't with <code>site=gl</code>), I found that URLs at GitLab don't accept the same shortened Git commit IDs as those at SourceForge:
https://sourceforge.net/p/flightgear/fgdata/ci/807062 - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062 - NOK
https://gitlab.com/flightgear/fgdata/-/commit/807062d - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062d0b6f858885547f27325e829c2bf42a12b - OK

As a consequence, there are probably a lot of broken links in the wiki due to shortened commit IDs. Better always use the long ones...

{{Note|Commit ID 807062 in FGData is not ambiguous at the time of this writing.}}
[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 15:45, 3 December 2025 (UTC)

: I have modified {{tl|Simgear_commit}}, {{tl|Flightgear_commit}}, {{tl|Fgdata_commit}}, etc. (12 templates!) to show a commit ID truncated to 7 characters in the automatically generated link text, so there is no excuse for not using long commit IDs anymore when using these templates (see the result [[Howto:Building_FlightGear_without_HiDPI_support#Commits|here]] for instance). Thanks to [[User:Gijs|Gijs]] for installing [https://en.wikipedia.org/wiki/Module:Ustring Module:Ustring] which made this possible!

: Note that manually provided ''text'' arguments are not truncated.

: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 10:10, 25 December 2025 (UTC)

Template:Fgdata-old commit

2025-12-25T09:56:34Z