User:Rominet: Difference between revisions

Jump to navigation Jump to search

User:Rominet (view source)

Revision as of 17:58, 9 April 2019

17,792 bytes added ,  9 April 2019
→‎Getting started with download_and_compile.sh: English instructions essentially ready (would need a bit more proofreading, mostly)
m (Intro: remove some bold formatting for more clarity)
(→‎Getting started with download_and_compile.sh: English instructions essentially ready (would need a bit more proofreading, mostly))
Line 28: Line 28:
=== Getting started with <tt>download_and_compile.sh</tt> ===
=== Getting started with <tt>download_and_compile.sh</tt> ===


To be completed. In the mean time, see [https://sourceforge.net/p/flightgear/mailman/message/36633375/ this message] on the flightgear-devel mailing list (which should be fine!).
This text in this section corresponds to the method described in [https://sourceforge.net/p/flightgear/mailman/message/36633375/ this message] on the <tt>flightgear-devel</tt> mailing list. It is more detailed, though, and should hopefully be easier to follow for non- experts.
 
We'll first explain how to get <tt>download_and_compile.sh</tt> in a way that makes updates easy and causes the command
download_and_compile.sh --version
to work as intended (the “version” is a Git blob id such as <tt>6a5e4f05e2ccf27115eec58313be027b11266097</tt><ref name="not-on-download-and-compile-sh-version-being-a-Git-blob-id">It's admittedly not very pretty, but is automatically updated by Git every time you update <tt>download_and_compile.sh</tt> as we're about to see, which is very convenient and compensates for the ugliness</ref>). Then we'll show you how to clone the large [https://sourceforge.net/p/flightgear/fgdata/ref/next/ FGData] repository, and finally give the last instructions to get FlightGear up and running.
 
==== Getting <tt>download_and_compile.sh</tt> the “right way” ====
 
Go to a directory (folder) of your choice. Let's assume it is <tt>~/flightgear</tt>, but really, you can choose whatever you want. Now clone the [https://sourceforge.net/p/flightgear/fgmeta/ci/next/tree/ FGMeta] repository:
mkdir -p ~/flightgear
cd ~/flightgear
git clone https://git.code.sf.net/p/flightgear/fgmeta
You now have a fresh <tt>download_and_compile.sh</tt> script in <tt>~/flightgear/fgmeta</tt>. Want 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, CMAKE, OSG, PLIB, OPENRTI, SIMGEAR, FGFS, DATA, FGRUN, FGO, FGX,
  OPENRADAR, ATCPIE, TERRAGEAR, TERRAGEARGUI
 
Available options:
  -h, --help    show this help message and exit
      --version print version and license information, then exit
 
(...)</pre>
 
Now that you have <tt>download_and_compile.sh</tt> from the [https://sourceforge.net/p/flightgear/fgmeta/ci/next/tree/ 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
Simple, isn't it? If you want to see the latest commits affecting <tt>download_and_compile.sh</tt>, it is quite easy too:
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>)
The same with patches?
cd ~/flightgear/fgmeta
git log -p -- download_and_compile.sh
 
All will be well as long as you ''don't modify anything yourself'' inside your [https://sourceforge.net/p/flightgear/fgmeta/ci/next/tree/ FGMeta] clone. <tt>download_and_compile.sh</tt> has plenty of options that should make it completely unnecessary to modify the script. Just run <code>download_and_compile.sh --help</code> and learn about the available options when you feel you need to change something.
 
Normal people will now skip to the next heading.
 
Still reading? Oh well... If you really, ''really'' want to modify the script, the easiest way 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, read Git tutorials if you want to learn that. Make sure your FGMeta repository is clean (use <code>git status</code>); then you can update it with:
 
# --rebase will apply your commits on top of the latest state of the repository
cd ~/flightgear/fgmeta && git pull --rebase
 
If 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.
 
==== Using <tt>download_and_compile.sh</tt> to build 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 the preceding section and see the command:
download_and_compile.sh --help
what you should actually is run:
~/flightgear/fgmeta/download_and_compile.sh --help
Apart from this harmless command, ''don't'' 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, but I don't guarantee others).
 
Of course, it's 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]) or by adding the directory containing <tt>download_and_compile.sh</tt> to your <tt>PATH</tt>.
 
{{Note|The following commands should be run from an empty<ref name="dedicated-directory-won-t-stay-empty-forever">Well, empty before the first time, but later <tt>download_and_compile.sh</tt> is going to populate it with plenty of FlightGear files and subdirectories, of course.</ref> directory in a partition that has enough free space for FGData (it currently takes 4.6 gigabytes (GB) and you'll also need several more to download the FlightGear sources and build them). The usual message printed by <tt>download_and_compile.sh</tt> recommends 12 or more gigabytes. We'll call the chosen directory ''$dir'' (for instance, you could choose <tt>~/flightgear/dnc-managed</tt>).
 
'''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 [https://sourceforge.net/p/flightgear/fgmeta/ci/next/tree/ FGMeta] clone.}}
 
{{Note|In what follows, we'll 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|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><nowiki>--sudo</nowiki></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>. You can use another one if you want, 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 we promised you. 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 the directory we called ''$dir'' above, 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 redownload all the FlightGear repositories every time you run it; that would be completely unmanageable).
 
Ready? Let's go!
<pre>
$ cd "$dir"
$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:username DATA
**************************************
*                                    *
* Warning, the compilation process  *
* is going to use 12 or more Gbytes  *
* of space and at least a couple of  *
* hours to download and build FG.    *
*                                    *
* Please, be patient ......          *
*                                    *
**************************************
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://username@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>
 
Here, it took us several minutes to verify on 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] 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>.
 
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 <tt>download_and_compile.sh</tt> command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:username DATA
**************************************
*                                    *
* Warning, the compilation process  *
* is going to use 12 or more Gbytes  *
* of space and at least a couple of  *
* hours to download and build FG.    *
*                                    *
* Please, be patient ......          *
*                                    *
**************************************
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://username@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>git clone ssh://username@git.code.sf.net/p/flightgear/fgdata</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)<br />
No worries. Just as before, simply rerun the command with the same arguments:
<pre>$ download_and_compile.sh --git-clone-site-params SourceForge=ssh:username DATA
**************************************
*                                    *
* Warning, the compilation process  *
* is going to use 12 or more Gbytes  *
* of space and at least a couple of  *
* hours to download and build FG.    *
*                                    *
* Please, be patient ......          *
*                                    *
**************************************
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>''$dir''/install/flightgear/fgdata</tt>, where ''$dir'' is the directory from which you ran <tt>download_and_compile.sh</tt>. Note this place: the full path of the <tt>''$dir''/install/flightgear/fgdata</tt> directory is your [[$FG_ROOT]].
 
Now open the <tt>[[$FG_ROOT]]/.git/config</tt> file that lives inside your FGData clone (i.e., <tt>''$dir''/install/flightgear/fgdata/.git/config</tt>). You should see a paragraph resembling this:
[remote "origin"]
        url = ssh://''username''@git.code.sf.net/p/flightgear/fgdata
        fetch = +refs/heads/*:refs/remotes/origin/*
Replace <code>ssh://''username''@</code> with <code>https://</code> and save the file. 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:
download_and_compile.sh
 
from the same directory as before (what we called <tt>''$dir''</tt> above). If you pass no option as done here, it will take 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 [https://sourceforge.net/p/flightgear/simgear/ci/next/tree/ SimGear], [https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/ FlightGear] and [https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/ FGData] repositories). Therefore, the above command is presently exactly equivalent to:
download_and_compile.sh SIMGEAR FGFS DATA
 
In case you wanted to build another component such as <tt>OSG</tt> (OpenSceneGraph), you could add it to the command, like this:
download_and_compile.sh SIMGEAR FGFS DATA OSG
 
(With current Debian stable, this is not necessary because it has OpenSceneGraph 3.4. But if your distribution only has an older version, you'll certainly need to select the <tt>OSG</tt> component like this.)
 
When the command terminates, you should have a script called <tt>run_fgfs.sh</tt> in the directory ''$dir'' from which you ran <tt>download_and_compile.sh</tt>. This will be your script to run FlightGear. For instance, in order to start the built-in launcher, simply run the following command from ''$dir'':
./run_fgfs.sh --launcher
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!).


== Français ==
== Français ==
Rominet
377

edits

Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/117753"

Navigation menu