377
edits
Scripted Compilation on Linux Debian/Ubuntu: Difference between revisions
Jump to navigation
Jump to search
Scripted Compilation on Linux Debian/Ubuntu (view source)
Revision as of 16:09, 18 December 2022
, 18 December 2022→Task-specific instructions: Add subsection “Overriding the source repository or branch for a component”
(→Choosing between stable and development versions: Update: the --cleanup option opens interesting possibilities here) |
(→Task-specific instructions: Add subsection “Overriding the source repository or branch for a component”) |
||
| Line 519: | Line 519: | ||
{{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.}} | {{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-342-1</tt> of the Git repository located at [https://github.com/zakalawe/osg.git https://github.com/zakalawe/osg.git]. 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=GitHub:github.com/zakalawe/osg.git \ | |||
--component-branch OSG=fgfs-342-1 SIMGEAR FGFS DATA OSG | |||
==== The site name ==== | |||
<tt>download_and_compile.sh</tt> uses case-insensitive short names such as <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>GitHub</tt> (resp. <tt>SourceForge</tt>) site name to identify the settings used when cloning a repository from github.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>git.code.sf.net/p/flightgear/simgear</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 === | === Passing custom arguments to CMake === | ||