ld: File Commands

1 
1 3.4.2 Commands Dealing with Files
1 ---------------------------------
1 
1 Several linker script commands deal with files.
1 
1 'INCLUDE FILENAME'
1      Include the linker script FILENAME at this point.  The file will be
1      searched for in the current directory, and in any directory
1      specified with the '-L' option.  You can nest calls to 'INCLUDE' up
1      to 10 levels deep.
1 
1      You can place 'INCLUDE' directives at the top level, in 'MEMORY' or
1      'SECTIONS' commands, or in output section descriptions.
1 
1 'INPUT(FILE, FILE, ...)'
1 'INPUT(FILE FILE ...)'
1      The 'INPUT' command directs the linker to include the named files
1      in the link, as though they were named on the command line.
1 
1      For example, if you always want to include 'subr.o' any time you do
1      a link, but you can't be bothered to put it on every link command
1      line, then you can put 'INPUT (subr.o)' in your linker script.
1 
1      In fact, if you like, you can list all of your input files in the
1      linker script, and then invoke the linker with nothing but a '-T'
1      option.
1 
1      In case a "sysroot prefix" is configured, and the filename starts
1      with the '/' character, and the script being processed was located
1      inside the "sysroot prefix", the filename will be looked for in the
1      "sysroot prefix".  Otherwise, the linker will try to open the file
1      in the current directory.  If it is not found, the linker will
1      search through the archive library search path.  The "sysroot
1      prefix" can also be forced by specifying '=' as the first character
1      in the filename path, or prefixing the filename path with
11      '$SYSROOT'.  See also the description of '-L' in ⇒Command Line
      Options Options.
1 
1      If you use 'INPUT (-lFILE)', 'ld' will transform the name to
1      'libFILE.a', as with the command line argument '-l'.
1 
1      When you use the 'INPUT' command in an implicit linker script, the
1      files will be included in the link at the point at which the linker
1      script file is included.  This can affect archive searching.
1 
1 'GROUP(FILE, FILE, ...)'
1 'GROUP(FILE FILE ...)'
1      The 'GROUP' command is like 'INPUT', except that the named files
1      should all be archives, and they are searched repeatedly until no
1      new undefined references are created.  See the description of '-('
1      in ⇒Command Line Options Options.
1 
1 'AS_NEEDED(FILE, FILE, ...)'
1 'AS_NEEDED(FILE FILE ...)'
1      This construct can appear only inside of the 'INPUT' or 'GROUP'
1      commands, among other filenames.  The files listed will be handled
1      as if they appear directly in the 'INPUT' or 'GROUP' commands, with
1      the exception of ELF shared libraries, that will be added only when
1      they are actually needed.  This construct essentially enables
1      '--as-needed' option for all the files listed inside of it and
1      restores previous '--as-needed' resp.  '--no-as-needed' setting
1      afterwards.
1 
1 'OUTPUT(FILENAME)'
1      The 'OUTPUT' command names the output file.  Using
1      'OUTPUT(FILENAME)' in the linker script is exactly like using '-o
11      FILENAME' on the command line (⇒Command Line Options
      Options.).  If both are used, the command line option takes
1      precedence.
1 
1      You can use the 'OUTPUT' command to define a default name for the
1      output file other than the usual default of 'a.out'.
1 
1 'SEARCH_DIR(PATH)'
1      The 'SEARCH_DIR' command adds PATH to the list of paths where 'ld'
1      looks for archive libraries.  Using 'SEARCH_DIR(PATH)' is exactly
11      like using '-L PATH' on the command line (⇒Command Line
      Options Options.).  If both are used, then the linker will search
1      both paths.  Paths specified using the command line option are
1      searched first.
1 
1 'STARTUP(FILENAME)'
1      The 'STARTUP' command is just like the 'INPUT' command, except that
1      FILENAME will become the first input file to be linked, as though
1      it were specified first on the command line.  This may be useful
1      when using a system in which the entry point is always the start of
1      the first file.
1