From aaa3da966583bd64ea241369385ebeff8a801c1e Mon Sep 17 00:00:00 2001 From: Reid Spencer Date: Tue, 17 Aug 2004 09:18:37 +0000 Subject: [PATCH] Documented (Java properties file like) syntax of config file format Added definitions for some of the configuration items. Made the document HTML 4.01 Strict compliant. Ran ispell on it. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@15877 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CompilerDriver.html | 257 ++++++++++++++++++++++++++++----------- 1 file changed, 185 insertions(+), 72 deletions(-) diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html index 927ed766ca6..6697638c8cc 100644 --- a/docs/CompilerDriver.html +++ b/docs/CompilerDriver.html @@ -12,7 +12,7 @@ margin-right: 1em; margin-bottom: 1em; } .td_left { border: 2px solid gray; text-align: left; } - + @@ -86,8 +86,7 @@ interfaces need to be understood).
  • Supports source language translator invocation via both dynamically loadable shared objects and invocation of an executable.
    • - -

    + @@ -96,7 +95,7 @@

    At a high level, llvmc operation is very simple. The basic action taken by llvmc is to simply invoke some tool or set of tools to fill the user's request for compilation. Every execution of llvmctakes the - following sequence of steps:
    + following sequence of steps:

    Collect Command Line Options
    The command line options provide the marching orders to llvmc @@ -108,9 +107,10 @@
    Based on the options and the suffixes of the filenames presented, a set of configuration files are read to configure the actions llvmc will take. Configuration files are provided by either LLVM or the front end - compiler tools that B invokes. These files determine what actions - llvmc will take in response to the user's request. See the section - on configuration for more details.
    + compiler tools that llvmc invokes. These files determine what + actions llvmc will take in response to the user's request. See + the section on configuration for more details. +
    Determine Phases To Execute
    Based on the command line options and configuration files, llvmc determines the compilation phases that @@ -132,18 +132,18 @@
    If any action fails (returns a non-zero result code), llvmc also fails and returns the result code from the failing action. If everything succeeds, llvmc will return a zero result code.
    -

    +

    llvmc's operation must be simple, regular and predictable. Developers need to be able to rely on it to take a consistent approach to compilation. For example, the invocation:

    - 
    -   llvmc -O2 x.c y.c z.c -o xyz
     + + llvmc -O2 x.c y.c z.c -o xyz

    must produce exactly the same results as:

    - 
    -   llvmc -O2 x.c
-   llvmc -O2 y.c
-   llvmc -O2 z.c
-   llvmc -O2 x.o y.o z.o -o xyz
     + + llvmc -O2 x.c + llvmc -O2 y.c + llvmc -O2 z.c + llvmc -O2 x.o y.o z.o -o xyz

    To accomplish this, llvmc uses a very simple goal oriented procedure to do its work. The overall goal is to produce a functioning executable. To accomplish this, llvmc always attempts to execute a @@ -254,10 +254,11 @@

    An action, with regard to llvmc is a basic operation that it takes in order to fulfill the user's request. Each phase of compilation will invoke zero or more actions in order to accomplish that phase.

    -

    Actions come in two forms:

      +

      Actions come in two forms:

      +

      + @@ -274,9 +275,9 @@ llvmc. Configuration information is relatively static for a given release of LLVM and a front end compiler. However, the details may change from release to release of either. Users are encouraged to simply use - the various options of the B command and ignore the configuration of - the tool. These configuration files are for compiler writers and LLVM - developers. Those wishing to simply use B don't need to understand + the various options of the llvmc command and ignore the configuration + of the tool. These configuration files are for compiler writers and LLVM + developers. Those wishing to simply use llvmc don't need to understand this section but it may be instructive on how the tool works.

      @@ -300,9 +301,9 @@ were written for LLVM or not. Furthermore, not all compilation front ends will have the same capabilities. Some front ends will simply generate LLVM assembly code, others will be able to generate fully optimized byte code. In general, llvmc doesn't make any assumptions about the capabilities or command -line options of a sub-tool. It simply uses the details found in the configuration -files and leaves it to the compiler writer to specify the configuration -correctly.

      +line options of a sub-tool. It simply uses the details found in the +configuration files and leaves it to the compiler writer to specify the +configuration correctly.

      This approach means that new compiler front ends can be up and working very quickly. As a first cut, a front end can simply compile its source to raw @@ -336,15 +337,12 @@ optimization.

      Configuration Files
      -

      File Types

      -

      There are two types of configuration files: the master configuration file - and the language specific configuration file. The master configuration file - contains the general configuration of llvmc itself and is supplied - with the tool. It contains information that is source language agnostic. - Language specific configuration files tell llvmc how to invoke the - language's compiler for a variety of different tasks and what other tools - are needed to backfill the compiler's missing features (e.g. - optimization).

      +

      File Contents

      +

      Each configuration file provides the details for a single source language + that is to be compiled. This configuration information tells llvmc + how to invoke the language's pre-processor, translator, optimizer, assembler + and linker. Note that a given source language needn't provide all these tools + as many of them exist in llvm currently.

      Directory Search

      llvmc always looks for files of a specific name. It uses the @@ -365,77 +363,192 @@ optimization.

    1. If the configuration file sought still can't be found, llvmc will print an error message and exit.
    - The first file found in this search will be used. Other files with the same - name will be ignored even if they exist in one of the subsequent search +

    The first file found in this search will be used. Other files with the + same name will be ignored even if they exist in one of the subsequent search locations.

    File Names

    -

    In the directories searched, a file named master will be - recognized as the master configuration file for llvmc. Note that - users may override the master file with a copy in their home directory - but they are advised not to. This capability is only useful for compiler - implementers needing to alter the master configuration while developing - their compiler front end. When reading the configuration files, the master - files are always read first.

    -

    Language specific configuration files are given specific names to foster - faster lookup. The name of a given language specific configuration file is - the same as the suffix used to identify files containing source in that - language. For example, a configuration file for C++ source might be named - cpp, C, or cxx.

    +

    In the directories searched, each configuration file is given a specific + name to foster faster lookup (so llvmc doesn't have to do directory searches). + The name of a given language specific configuration file is simply the same + as the suffix used to identify files containing source in that language. + For example, a configuration file for C++ source might be named + cpp, C, or cxx. For languages that support multiple + file suffixes, multiple (probably identical) files (or symbolic links) will + need to be provided.

    What Gets Read

    -

    The master configuration file is always read. Which language specific - configuration files are read depends on the command line options and the - suffixes of the file names provided on llvmc's command line. Note +

    Which configuration files are read depends on the command line options and + the suffixes of the file names provided on llvmc's command line. Note that the --x LANGUAGE option alters the language that llvmc - uses for the subsequent files on the command line. Only the language - specific configuration files actually needed to complete llvmc's - task are read. Other language specific files will be ignored.

    + uses for the subsequent files on the command line. Only the configuration + files actually needed to complete llvmc's task are read. Other + language specific files will be ignored.

    Syntax
    -

    The syntax of the configuration files is yet to be determined. There are - two viable options remaining:
    +

    The syntax of the configuration files is very simple and somewhat + compatible with Java's property files. Here are the syntax rules:

    +
  • The file encoding is ASCII.
    • +
  • The file is line oriented. There should be one configuration item per + line. Lines are terminated by the newline character (0x0A).
    • +
  • A configuration item consists of a name, an = and a value.
    • +
  • A name consists of a sequence of identifiers separated by period.
    • +
  • An identifier consists of specific keywords made up of only lower case + and upper case letters (e.g. lang.name).
    • +
  • Values come in four flavors: booleans, integers, commands and + strings.
    • +
  • Valid "false" boolean values are false False FALSE no No NO + off Off and OFF.
    • +
  • Valid "true" boolean values are true True TRUE yes Yes YES + on On and ON.
    • +
  • Integers are simply sequences of digits.
    • +
  • Commands start with a program name and are followed by a sequence of + words that are passed to that program as command line arguments. Program + arguments that begin and end with the @ sign will have their value + substituted. Program names beginning with / are considered to be + absolute. Otherwise the PATH will be applied to find the program to + execute.
    • +
  • Strings are composed of multiple sequences of characters from the + character class [-A-Za-z0-9_:%+/\\|,] separated by white + space.
    • +
  • White space on a line is folded. Multiple blanks or tabs will be + reduced to a single blank.
    • +
  • White space before the configuration item's name is ignored.
    • +
  • White space on either side of the = is ignored.
    • +
  • White space in a string value is used to separate the individual + components of the string value but otherwise ignored.
    • +
  • Comments are introduced by the # character. Everything after a + # and before the end of line is ignored.
    • +
    -
    Configuration Items
    +
    Configuration Items
    -

    The following description of configuration items is syntax-less and simply - uses a naming hierarchy to describe the configuration items. Whatever - syntax is chosen will need to map the hierarchy to the given syntax.

    +

    The table below provides definitions of the allowed configuration items + that may appear in a configuration file. Every item has a default value and + does not need to appear in the configuration file. Missing items will have the + default value. Each identifier may appear as all lower case, first letter + capitalized or all upper case.

    + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + - - + + + translator generates. + - + - + + + + + + + + + + + + + + + + +
    Name Value Type DescriptionDefault

    LANG ITEMS

    lang.namestringProvides the common name for a language definition. + For example "C++", "Pascal", "FORTRAN", etc.blank
    Capabilities.hasPreProcessorlang.opt1stringSpecifies the parameters to give the optimizer when -O1 is + specified on the llvmc command line.-simplifycfg -instcombine -mem2reg
    lang.opt2stringSpecifies the parameters to give the optimizer when -O2 is + specified on the llvmc command line.TBD
    lang.opt3stringSpecifies the parameters to give the optimizer when -O3 is + specified on the llvmc command line.TBD
    lang.opt4stringSpecifies the parameters to give the optimizer when -O4 is + specified on the llvmc command line.TBD
    lang.opt5stringSpecifies the parameters to give the optimizer when -O5 is + specified on the llvmc command line.TBD

    PREPROCESSOR ITEMS

    preprocessor.commandcommandThis provides the command prototype that will be used + to run the preprocessor. Valid substitutions are @in@ for the + input file and @out@ for the output file. This is generally only + used with the -E option.<blank>
    preprocessor.required booleanThis item specifies whether the language has a - pre-processing phase or not. This controls whether the B<-E> option works - for the language or not.This item specifies whether the pre-processing phase + is required by the language. If the value is true, then the + preprocessor.command value must not be blank. With this option, + llvmc will always run the preprocessor as it assumes that the + translation and optimization phases don't know how to pre-process their + input.false

    TRANSLATOR ITEMS

    translator.commandcommandThis provides the command prototype that will be used + to run the translator. Valid substitutions are @in@ for the + input file and @out@ for the output file.<blank>
    Capabilities.outputFormat"bc" or "ll"translator.outputnative, bytecode or assembly This item specifies the kind of output the language's - compiler generates. The choices are either bytecode (bc) or LLVM - assembly (ll).bytecode
    Capabilities.understandsOptimizationtranslator.preprocesses booleanIndicates whether the compiler for this language understands the - -O options or notIndicates that the translator also preprocesses. If this is true, then + llvmc will skip the pre-processing phase whenever the final + phase is not pre-processing.false
    translator.optimizersbooleanIndicates that the translator also optimizes. If this is true, then + llvmc will skip the optimization phase whenever the final phase + is optimization or later.false
    translator.groks_dash_obooleanIndicates that the translator understands the intent of the + various -On options to llvmc. This will cause the + -On option to be based to the translator instead of the + equivalent options provided by lang.optn.false

    OPTIMIZER ITEMS

    ASSEMBLER ITEMS

    LINKER ITEMS