Compilation configuration file for GCC (Spec files)

compilation configuration file for GCC (Spec files)
3.15 Configuring external tool programs and Parameters

[Adie: This article was originally a section of the GCC Handbook, and 3.15 is the number in the manual.]

GCC is a driver-driven program. It calls other programs to compile, assemble, and link in turn. GCC parses the command-line arguments and then decides which subroutine to call and which parameters should be passed to the subroutine. All of these behaviors are controlled by the spec string (spec strings). Typically, each GCC can invoke a subroutine that corresponds to a spec string, but there are a few subroutines that require multiple spec strings to control their behavior. The spec string compiled into GCC can be overwritten by using the-specs= command-line parameter to specify a spec file (spec).

Spec files are used to configure spec strings. It contains a series of instructions separated by a blank line. The type of instruction is determined by the first non-whitespace character of a line, which may be:%command defines a preprocessing command for a spec file, and the preprocessing command includes the following command:%include < file> searches for a file and inserts its contents into the current location of the spec file.
%include_noerr < file> is the same as '%include ', but does not produce an error message if the file is not found.
%rename Old_name new_name renamed the SPEC string Old_name to New_name.
*[Spec_name]: This command lets the compiler create, overwrite, or delete the SEPC string for the specified name. All text after this instruction to the next instruction or to the empty line is considered to be the content of this SPEC string. If its contents are empty, then the name will be deleted (if the name does not exist, nothing will happen). When the content is not empty, if the name does not exist, a new SPEC string is created, and if it already exists, their contents will be replaced. If the first character of the content is ' + ', then the content is appended to the original definition, not overwritten.
[suffix]: Create a new ' [suffix] spec ' (suffix processing) combination. The SPEC string for this suffix is made up of lines that precede the next instruction or empty line. When the compiler encounters an input file that refers to this suffix, it executes the instructions in the SPEC string in turn, which indicates how to compile the file. For example:

          . ZZ:
          z-compile-input%i
     

It means: any to '. The input files at the end of ZZ will be processed using the ' Z-compile ' program and will be invoked using the-input switch and the '%i ' replacement result (see below) as the command-line argument.

As the content of the SPEC string, the text after the suffix instruction can also be one of the following: @ Language it indicates that the suffix is an alias for a known language. It is similar to the-X option in the GCC command line for the specified language. Like what:

               . ZZ:
               @c++
          

This shows. The ZZ file is actually a C + + source code file.
# NAME this produces an error message:

               The name compiler is not installed on the current system.
          

GCC has built up a huge list of suffixes. This directive adds suffixes to the end of the list, and since this list is used to search backwards from the end, this technique can actually be used to overwrite previous entries.

GCC has built in the following SPEC string. SPEC files can overwrite them or create new. Note that some implementations of GCC may also add their own SEPC strings to this list.

     The ASM pass to the assembler option Asm_final pass to    the post-assembly processor option
     CPP          passed to the C preprocessor option
     cc1          the option to pass to the C compiler
     Cc1plus The      option to pass to the C + + compiler endfile The end of the link to include the destination file that the link         passes to the linker's Options
     lib command line to the linker's          library to be included
     LIBGCC       decides which GCC support library
     linker       Set the linker's name
     predefines   the macro definition passed to the C preprocessor
     signed_  a macro passed to the CPP that describes whether Char is a signed type by default
     startfile the    target file to be passed to the linker at the outset

Here is an example of a simple SPEC file:

     %rename Lib                 old_lib
     
     *lib:
     --start-group-lgcc-lc-leval1--end-group% (old_lib)

This example renames ' Lib ' to ' old_lib ' and overwrites the previous ' Lib ' definition with a new definition. The new definition adds some additional command-line options before it contains the old definition text.

The SEPC string is a list of command-line options that are passed to the appropriate program. In addition, the SEPC string can contain '% ' as the prefix string to represent the variable. Variables can be used instead of a string of text, or as a condition to insert text into the command line. Using these concepts can result in very complex command lines.

Here are all the predefined variables for the SPEC string. Note that these variables do not automatically create spaces around the results when they represent text. You can use constant strings to link these variables when you link them. Percent is used to denote a '% ' in the program name or parameter.
%i used to indicate the input file name currently being processed
%b represents the basic name of the input file. It does not contain the last dot and subsequent content, nor does it include the pathname.
%B is the same as '%B ', but it contains the suffix (after the last dot).
%d flags a temporary file name with or appended with '%d ', and GCC automatically deletes the file with this tag when it exits normally. Unlike '%g ', this variable does not produce textual content in parameters.
%g suffix produces a file name with the specified suffix suffix, each time a compilation occurs. As with '%d ', it is also marked as a temporary file. To reduce the likelihood of a denial of service attack, the next file name is not expected, even if the last file name was known. For example, '%g.s ...%g.o%g.s ' may be converted to ' Ccuvuuau.s ccxyaxz12.o Ccuvuuau.s '. The suffix name needs to be able and ' [. A-za-z]* ' Such a regular expression matches or uses a specific '%O '. '%O ' When used, assume that it has been processed. Previously, '%g ' was simply a single occurrence that was replaced with a filename, which made the attack easy to succeed without a suffix.
%u suffix and '%g ', but each time a new temporary file name is generated, instead of one at a time of compilation.
%u suffix generates a file name the last time the '%usuffix ' was used, and if not previously, a new one is generated. Without using '%usuffix ', it's just like '%gsuffix ', except they don't share the suffix namespace. Therefore, '%g.s ...%u.s%g.s ...%u.s ' generates two different file names, one is '%g.s ' and the other is '%u.s '. Previously, '%u ' was replaced with the file name generated by the previous '%u ', without any suffix.
%j suffix If there is host_bit_bucket, and it is writable, and no-save-temps is used, this is replaced by the Host_bit_bucket name. Otherwise, a temporary file name is generated, and the '%u ' effect is the same. This temporary file is not intended to be used to communicate between two processes, but is treated as garbage.

[Adie:host_bit_bucket is a parameter used when configuring the host system environment in GCC. It is a path name defined by the host system and can be written as a file, but all writes are discarded. This is often referred to as a bit bucket (bit-stream bin ) or a null device (empty), which is usually/dev/null in UNIX.
%| suffix%m suffix and '%g ' are similar, just can use-pipe (pipe). When using pipes, '%| ' is replaced with a dash, '%m ' is replaced with empty. This is a common way for programs to read data from standard input and write data toward standard output. If you need to handle more complex situations, you can also use '%{pipe:x} ': Refer to the example in F/lang-specs.h.
%. SUFFIX replace the parameter that matches the suffix. Suffix to the space or the next% end.
%w the output file that contains or follows a parameter labeled '%w ' for this compilation. This will put this parameter to '%o ' The parameter sequence inside.
%o Replace all output file names and automatically place spaces around them. You should still be in '%o ' , or the result will be undefined. '%o ' Used to run the linker. Input files that do not have an identifiable suffix will not be compiled, but they are included in the output file, so they can be linked.
%O Replace the suffix for the destination file. Note that when it is immediately behind '%g,%u, and%u ', it is specially handled because they require a full file name. The method of processing is to assume '%O ' has been processed, unless '%g,%u, and%u ' are currently not supported using special '%O ' suffix, for example, '. O '.
The%p replaces the standard predetermined macros as the current target type. Used when running the CPP program.
%P is similar to '%P ', except that the name of each predefined macro is preceded by ' __ ' unless the name of the macro begins with ' __ ' or ' _l '. Where L is an uppercase letter. This is required by ISO C.
%I Refrigerator all-iprefix (from Gcc_exec_prefix),-isysroot (from Target_system_root),-isystem (from Compiler_path and-B options) and required-imulti Lib.
%s The current parameter is the name of a library or executable file. Search the standard directory list to find the file name and replace it with the full name if it is found. The current directory is included in the first bit of the scanned directory list.
%T The current parameter is a connection script. Search for that file in the directory list of the library file. If the file is found, insert a--script option and the full path name of the file to the command line. If the file is not found, an error message will be generated. Note that the current directory is not searched.
%e str Prints the STR as an error message. STR uses line wrapping as the end. It can be used when an inconsistent option is detected.
% (name) refrigerator the SPEC string content named name to the current position.
%x{option} adds a choice to '%x '.
%x outputs all linker options added with-W1 or '%x '.
%Y outputs all assembler options added with-wa.
%Z outputs all assembler options added with-WP.
%a processing ASM Spec. Used to calculate the switch passed to the assembler.
%A processing asm_final Spec. If you need to assemble the post processor, use it to calculate the options passed to the post-assembly processor.
%l processing link spec. Used to calculate the command-line arguments passed to the linker. It is generally used for '%l%G%s%d ' and%E ' sequences.
%d Export one-l option for all GCC-considered directories that may contain executables. If the target supports multiple libraries, then each directory will take into account the multi-Library directory.
%l handling Lib spec. This spec string determines which library files the connector's command line needs to contain.
%G processing LIBGCC spec. This SEPC string determines the GCC support libraries that are used in the command line arguments that are passed to the connector.
%s handles Startfile spec. This SEPC string represents the first destination file that is passed to the linker. Usually this file name is CRT0.O.
%E processing Endfile spec. Represents the last destination file that is passed to the linker.
%c processes CPP Spec. Used to construct parameters passed to the C preprocessor.
%1 handles CC1 spec. Used to construct the options passed to the current C compiler (' cc1 ').
%2 handles Cc1plus spec. Used to construct the options passed to the current C + + compiler (' Cc1plus ').
%* replaces the variable portion of the matching option. See below. Note that the comma in the replacement string is replaced by a space.
%<s Delete all the-s options in the command line. Note that this command is location-dependent. In the SPEC string, the-s before this command is removed, not later.
%: function (args) invokes the specified name and passes the arguments. The parameter is first treated as a nested SPEC string and then split into an array of parameters. The function returns a string that is inserted where the current command is located.

The following is the built-in spec function: getenv getenv spec function with two parameters: an environment variable name and a string. If the environment variable is not defined, a critical error is generated. The return value is the value of the environment variable and the string is concatenated together. For example, if Topdir is defined as/path/to/top, then:

               %:getenv (Topdir/include)

will be expanded into/path/to/top/include.
The if-exists if-exists function takes one parameter, the absolute pathname of a file. If the file exists, If-exists returns the path name. Here is a simple example of usage:

               *startfile:
               crt0%o%s%:if-exists (crti%o%s) crtbegin%o%s

The If-exists-else if-exists-else function is similar to the if-exists function, unlike it with two parameters. The first parameter is the path name of the file. If the file exists, the If-exists-else function returns the path name. If it does not exist, the second argument is returned. This allows the If-exists-else function to select the file or other depending on whether the file exists. Here is an example of use:

               *startfile:
               crt0%o%s%:if-exists (crti%o%s) \
               %:if-exists-else (crtbegint%o%s crtbegin%o%s)

The Replace-outfile replace-outfile function has two parameters. It looks for the first parameter in the output file array and replaces it with the second parameter. Here's an example:

               %{fgnu-runtime:%:replace-outfile (-LOBJC-LOBJC-GNU)}

The Remove-outfile remove-outfile function takes one parameter. It looks up this parameter in an array of output files and deletes it. Example:

               %:remove-outfile (-LM)

Pass-through-libs Pass-through-libs can take any number of parameters. It looks for the-l option and non-option content that ends with. A (make sure that the library file for the linker is entered), adds a-plugin-opt=-pass-through= prefix to all the found parameters, and returns after a space separation. This list is used to pass to the LTO linker plug-in.

               %:p ass-through-libs (%G%l%G)

The Print-asm-header Print-asm-header function does not take parameters, it simply prints the following slogan:

               Assembler options
               ================= use
               
               '-wa,option ' to pass ' OPTION ' to the assembler.

It is used to separate compiler options and assembler options in the output using--TARGET-HELP.
%{s} If you pass the-s option to GCC, replace this option. If there is, it does nothing. Note that the leading dash for this option will be added automatically when replaced. Therefore, the SPEC string '%{foo} ' matches the-foo option in the command line and outputs a-foo.
%w{s} and%{s} are similar, except that the last supplied parameter is marked as a file, and the file is deleted when it fails.
%{s*} Refrigerator All the options that start with-S that are passed to GCC, usually with one parameter. This is used primarily for options such as-O,-D,-I, and so on.  GCC believes that-o foo is an option whose name begins with ' O '. '%{o*} ' to replace this, including spaces. As a result, two parameters will be generated.
%{s*&t*} and%{s*} are similar, just keep the S and T options in order (the order of S and T in SEPC is not important). You can use any number of & delimited variables, each of which is optional. More useful examples of CPP are: '%{d*&u*&a*} '.
%{S:X} If the-S option is used in GCC, use X instead.
%{! S:X} If you do not use the-S option in GCC, replace it with X.
%{S*:X} If you have one or more options that start with-S, replace them with X. Usually, no matter how many times the option appears, it is replaced by only one X. However, if X contains '%* ', then each option will be replaced by an X, where '%* ' is matched by the option Partial substitution of ' * '.
%{. S:X} If the processed file starts with S, it is replaced by X
%{!. S:X} If you do not process a file that begins with S, replace it with X
%{,S:X} If the file being processed is in the S language, replace it with X
%{!,S:X} If you do not have a file in the S language, replace it with X
%{s| P:X} If the-S or-P option is provided, it is replaced by X. It can also be combined with '! ', '. ', ', ' and *, although they have stronger constraints than ' | '. If '%* ' appears in X, all replacements need to use ' * ', and only the first matching substitution is used.

For example, a SEPC string such as the following:

          %{.c:-foo}%{!. C:-bar}%{.c|d:-baz}%{!. C|d:-boggle}

Then enter the command line and the corresponding output as follows:

          FRED.C        -foo-baz
          jim.d         -bar-boggle-
          D fred.c     -foo-baz-boggle-
          d jim.d      -bar-baz-boggle

%{s:x; T:y; :D} If GCC contains the-S option, replace it with X, otherwise, if it contains-T, replace with Y, otherwise, replace with D. You can add as many clauses as you like. It can also be combined with '. ', ', ', '! ', ' | ' and ' * '.

The X in the conditional statement%{s:x} and similar structures can contain nested '% ' structures, spaces, and even line breaks. As described above, they work as usual. Spaces at the end of X are ignored. A space can also appear to the left of the colon, but it cannot appear between '. ' or ' * ' and match words.

In these structures,-o,-F,-M, and-w options are handled specially. If there are other-o options or have the opposite option for-F,-M,-W, the previous value will be ignored unless the S in {s*} have only one letter. All occurrences can pass when there is only one letter.

The ' | ' character appears at the beginning of the predicate to indicate that the next command should use the pipeline, but only if-pipe is used.

Which options require the use of parameters is built into GCC inside. (You may be thinking that it is useful to define which options require parameters by using different compiler sepc. However, this is not possible at this time. If you do not know which options require parameters, GCC cannot decide which input file to compile. GCC must know the input file to decide which compiler to use.

GCC also knows that parameters that begin with-L are processed as a compiled output file and passed to the linker in its place in other output files.