doc/ld.html/File-Commands.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the GNU linker LD
(GNU Toolchain for the A-profile Architecture 10.3-2021.07 (arm-10.29))
version 2.36.1.

Copyright (C) 1991-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the
section entitled "GNU Free Documentation License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>LD: File Commands</title>

<meta name="description" content="LD: File Commands">
<meta name="keywords" content="LD: File Commands">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Simple-Commands.html#Simple-Commands" rel="up" title="Simple Commands">
<link href="Format-Commands.html#Format-Commands" rel="next" title="Format Commands">
<link href="Entry-Point.html#Entry-Point" rel="previous" title="Entry Point">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="File-Commands"></a>
<div class="header">
<p>
Next: <a href="Format-Commands.html#Format-Commands" accesskey="n" rel="next">Format Commands</a>, Previous: <a href="Entry-Point.html#Entry-Point" accesskey="p" rel="previous">Entry Point</a>, Up: <a href="Simple-Commands.html#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Commands-Dealing-with-Files"></a>
<h4 class="subsection">3.4.2 Commands Dealing with Files</h4>
<a name="index-linker-script-file-commands"></a>
<p>Several linker script commands deal with files.
</p>
<dl compact="compact">
<dt><code>INCLUDE <var>filename</var></code></dt>
<dd><a name="index-INCLUDE-filename"></a>
<a name="index-including-a-linker-script"></a>
<p>Include the linker script <var>filename</var> at this point.  The file will
be searched for in the current directory, and in any directory specified
with the <samp>-L</samp> option.  You can nest calls to <code>INCLUDE</code> up to
10 levels deep.
</p>
<p>You can place <code>INCLUDE</code> directives at the top level, in <code>MEMORY</code> or
<code>SECTIONS</code> commands, or in output section descriptions.
</p>
</dd>
<dt><code>INPUT(<var>file</var>, <var>file</var>, &hellip;)</code></dt>
<dt><code>INPUT(<var>file</var> <var>file</var> &hellip;)</code></dt>
<dd><a name="index-INPUT_0028files_0029"></a>
<a name="index-input-files-in-linker-scripts"></a>
<a name="index-input-object-files-in-linker-scripts"></a>
<a name="index-linker-script-input-object-files"></a>
<p>The <code>INPUT</code> command directs the linker to include the named files
in the link, as though they were named on the command line.
</p>
<p>For example, if you always want to include <samp>subr.o</samp> any time you do
a link, but you can&rsquo;t be bothered to put it on every link command line,
then you can put &lsquo;<samp>INPUT (subr.o)</samp>&rsquo; in your linker script.
</p>
<p>In fact, if you like, you can list all of your input files in the linker
script, and then invoke the linker with nothing but a &lsquo;<samp>-T</samp>&rsquo; option.
</p>
<p>In case a <em>sysroot prefix</em> is configured, and the filename starts
with the &lsquo;<samp>/</samp>&rsquo; character, and the script being processed was
located inside the <em>sysroot prefix</em>, the filename will be looked
for in the <em>sysroot prefix</em>.  The <em>sysroot prefix</em> can also be forced by specifying
<code>=</code> as the first character in the filename path, or prefixing the
filename path with <code>$SYSROOT</code>. See also the description of
&lsquo;<samp>-L</samp>&rsquo; in <a href="Options.html#Options">Command-line Options</a>.
</p>
<p>If a <em>sysroot prefix</em> is not used then the linker will try to open
the file in the directory containing the linker script.  If it is not
found the linker will then search the current directory.  If it is still
not found the linker will search through the archive library search
path.
</p>
<p>If you use &lsquo;<samp>INPUT (-l<var>file</var>)</samp>&rsquo;, <code>ld</code> will transform the
name to <code>lib<var>file</var>.a</code>, as with the command-line argument
&lsquo;<samp>-l</samp>&rsquo;.
</p>
<p>When you use the <code>INPUT</code> command in an implicit linker script, the
files will be included in the link at the point at which the linker
script file is included.  This can affect archive searching.
</p>
</dd>
<dt><code>GROUP(<var>file</var>, <var>file</var>, &hellip;)</code></dt>
<dt><code>GROUP(<var>file</var> <var>file</var> &hellip;)</code></dt>
<dd><a name="index-GROUP_0028files_0029"></a>
<a name="index-grouping-input-files"></a>
<p>The <code>GROUP</code> command is like <code>INPUT</code>, except that the named
files should all be archives, and they are searched repeatedly until no
new undefined references are created.  See the description of &lsquo;<samp>-(</samp>&rsquo;
in <a href="Options.html#Options">Command-line Options</a>.
</p>
</dd>
<dt><code>AS_NEEDED(<var>file</var>, <var>file</var>, &hellip;)</code></dt>
<dt><code>AS_NEEDED(<var>file</var> <var>file</var> &hellip;)</code></dt>
<dd><a name="index-AS_005fNEEDED_0028files_0029"></a>
<p>This construct can appear only inside of the <code>INPUT</code> or <code>GROUP</code>
commands, among other filenames.  The files listed will be handled
as if they appear directly in the <code>INPUT</code> or <code>GROUP</code> commands,
with the exception of ELF shared libraries, that will be added only
when they are actually needed.  This construct essentially enables
<samp>--as-needed</samp> option for all the files listed inside of it
and restores previous <samp>--as-needed</samp> resp. <samp>--no-as-needed</samp>
setting afterwards.
</p>
</dd>
<dt><code>OUTPUT(<var>filename</var>)</code></dt>
<dd><a name="index-OUTPUT_0028filename_0029"></a>
<a name="index-output-file-name-in-linker-script"></a>
<p>The <code>OUTPUT</code> command names the output file.  Using
<code>OUTPUT(<var>filename</var>)</code> in the linker script is exactly like using
&lsquo;<samp>-o <var>filename</var></samp>&rsquo; on the command line (see <a href="Options.html#Options">Command
Line Options</a>).  If both are used, the command-line option takes
precedence.
</p>
<p>You can use the <code>OUTPUT</code> command to define a default name for the
output file other than the usual default of <samp>a.out</samp>.
</p>
</dd>
<dt><code>SEARCH_DIR(<var>path</var>)</code></dt>
<dd><a name="index-SEARCH_005fDIR_0028path_0029"></a>
<a name="index-library-search-path-in-linker-script"></a>
<a name="index-archive-search-path-in-linker-script"></a>
<a name="index-search-path-in-linker-script"></a>
<p>The <code>SEARCH_DIR</code> command adds <var>path</var> to the list of paths where
<code>ld</code> looks for archive libraries.  Using
<code>SEARCH_DIR(<var>path</var>)</code> is exactly like using &lsquo;<samp>-L <var>path</var></samp>&rsquo;
on the command line (see <a href="Options.html#Options">Command-line Options</a>).  If both
are used, then the linker will search both paths.  Paths specified using
the command-line option are searched first.
</p>
</dd>
<dt><code>STARTUP(<var>filename</var>)</code></dt>
<dd><a name="index-STARTUP_0028filename_0029"></a>
<a name="index-first-input-file"></a>
<p>The <code>STARTUP</code> command is just like the <code>INPUT</code> command, except
that <var>filename</var> will become the first input file to be linked, as
though it were specified first on the command line.  This may be useful
when using a system in which the entry point is always the start of the
first file.
</p></dd>
</dl>

<hr>
<div class="header">
<p>
Next: <a href="Format-Commands.html#Format-Commands" accesskey="n" rel="next">Format Commands</a>, Previous: <a href="Entry-Point.html#Entry-Point" accesskey="p" rel="previous">Entry Point</a>, Up: <a href="Simple-Commands.html#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>