377
edits
Scripted Compilation on Linux Debian/Ubuntu: Difference between revisions
Scripted Compilation on Linux Debian/Ubuntu (view source)
Revision as of 19:49, 14 November 2020
, 14 November 2020Document the new option --old-lts and replace “Long Term Support” with “Long Term Stable” (James once wrote on FlightGear-devel that this is the right meaning of “LTS” in the case of FG).
(Document new options --sg-cmake-arg and --fg-cmake-arg) |
(Document the new option --old-lts and replace “Long Term Support” with “Long Term Stable” (James once wrote on FlightGear-devel that this is the right meaning of “LTS” in the case of FG).) |
||
| Line 42: | Line 42: | ||
}}. 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]]. | }}. 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 the <code>-s</code> | 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. | ||
== <span id="getting-started-with-download-and-compile-sh"></span> Getting started with <tt>download_and_compile.sh</tt> == | == <span id="getting-started-with-download-and-compile-sh"></span> Getting started with <tt>download_and_compile.sh</tt> == | ||
| Line 56: | Line 56: | ||
./run_fgfs.sh --launcher | ./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 | 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>. | 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>. | ||
| Line 148: | Line 148: | ||
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]]. | 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 | {{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 three base components needed to run FlightGear: <tt>SIMGEAR</tt>, <tt>FGFS</tt> and <tt>DATA</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 {{simgear source | When you don't pass any non-option argument to <tt>download_and_compile.sh</tt> as done here, it takes care of the three base components needed to run FlightGear: <tt>SIMGEAR</tt>, <tt>FGFS</tt> and <tt>DATA</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 {{simgear source | ||
| Line 161: | Line 161: | ||
In case you want to build another component such as [[OpenSceneGraph|OSG]], you can add it to the command, like this: | In case you want to build another component such as [[OpenSceneGraph|OSG]], you can add it to the command, like this: | ||
$ download_and_compile.sh -s -j$(nproc) SIMGEAR FGFS DATA OSG | $ download_and_compile.sh -s -j$(nproc) SIMGEAR FGFS DATA OSG | ||
(explicitly specifying OSG like this is necessary as of | (explicitly specifying OSG like this is necessary as of November 2020 if you build with <code>--old-lts</code> instead of <code>-s</code> and the version of the [[OpenSceneGraph]] library in your distribution is 3.5 or later). | ||
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> | 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> | ||
| Line 173: | Line 173: | ||
=== <span id="using-download-and-compile-sh-to-update-flightgear"></span> Updating FlightGear === | === <span id="using-download-and-compile-sh-to-update-flightgear"></span> Updating FlightGear === | ||
{{Note|If you built FlightGear with either <code>-s</code> | {{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 | 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 | ||
| Line 229: | Line 229: | ||
{{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.).}} | {{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 | {{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). | 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). | ||
| Line 423: | Line 423: | ||
== When building ''next'', you may encounter problems == | == 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 | 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. | 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 | {{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 == | == Task-specific instructions == | ||
| Line 448: | Line 448: | ||
=== Choosing between stable and development versions === | === 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> and <code>--lts</code> options: | 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...'' | $ download_and_compile.sh -s ''COMPONENT1 COMPONENT2...'' | ||
or | or | ||
$ download_and_compile.sh --lts ''COMPONENT1 COMPONENT2...'' | $ download_and_compile.sh --lts ''COMPONENT1 COMPONENT2...'' | ||
or | |||
$ download_and_compile.sh --old-lts ''COMPONENT1 COMPONENT2...'' | |||
How does it work? | How does it work? | ||
* For [[SimGear]], FlightGear and [[FGData]], <code>-s</code> uses the most recent stable release branch of the corresponding Git repository, | * 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> or <code>--lts</code>. | * 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>. | ||
{{Warning|In a given folder where <tt>download_and_compile.sh</tt> is run, you should either always use the <code>-s</code> option, or always use | {{Warning|In a given folder where <tt>download_and_compile.sh</tt> is run, you should 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, better stick to the same suite: latest stable, latest LTS, previous LTS or ''next'', consistently accross all components.}} | ||
So, as far as the SIMGEAR, FGFS and DATA components are concerned, you can: | 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 stable release (<code>-s</code>); | ||
* build the latest Long Term | * 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 | * build the current development version (bleeding edge), which lives in the {{flightgear source | ||
| branch = next | | branch = next | ||
| text = next | | text = next | ||
}} branch of the FlightGear repository. | }} branch of the FlightGear repository. | ||
The use of <code>-s</code> or <code>--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). | 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). | ||
==== Building the latest Long Term | ==== 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 | 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 | $ cd ~/flightgear/dnc-managed | ||
$ download_and_compile.sh --lts | $ download_and_compile.sh --lts | ||
| Line 492: | Line 495: | ||
{{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.}} | {{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.}} | |||
=== Passing custom arguments to CMake === | === Passing custom arguments to CMake === | ||
| Line 654: | Line 666: | ||
* Build the latest stable release: <code>-s</code> | * Build the latest stable release: <code>-s</code> | ||
* Build the latest Long Term | * Build the latest Long Term Stable release: <code>--lts</code> | ||
* Build the previous Long Term Stable release: <code>--old-lts</code> | |||
Long Term | 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 | 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 === | === Skipping most prompts === | ||