Difference between revisions of "Compiler options file"

From Code::Blocks
(Updated options.)
m
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Proposed format for storing compiler options in editable XML. See: [/index.php/topic,16463.0.html XML based compilers].
+
[[Category:Code::Blocks Documentation]]
 +
[[Category:Developer Documentation]]
 +
Format for storing compiler options in editable XML.
  
  
Line 23: Line 25:
 
Standard <tt>if</tt> statement; contents of <tt>if</tt> block is evaluated if the <tt>if</tt> statement is true, otherwise the <tt>else</tt> block is evaluated (the <tt>else</tt> block is optional). Nesting is allowed.
 
Standard <tt>if</tt> statement; contents of <tt>if</tt> block is evaluated if the <tt>if</tt> statement is true, otherwise the <tt>else</tt> block is evaluated (the <tt>else</tt> block is optional). Nesting is allowed.
  
<tt>platform="</tt><os><tt>"</tt> (platform is the only condition currently defined). <os> is one of:
+
<tt>platform="</tt><os><tt>"</tt>. <os> is one of:
 
* <tt>windows
 
* <tt>windows
 
* macosx
 
* macosx
Line 33: Line 35:
 
* solaris
 
* solaris
 
* unix</tt>
 
* unix</tt>
 +
<source lang="xml" enclose="div">
 +
<if exec="bison -h">
 +
[...]
 +
</if>
 +
</source>
 +
True if the the command <tt>exec</tt> can be run.
 +
 +
<source lang="xml" enclose="div">
 +
<if exec="C -dumpversion"
 +
    regex="^4\.[3-9]|^[5-9]\.[0-9]"
 +
    default="true">
 +
[...]
 +
</if>
 +
</source>
 +
If the text before the first space in <tt>exec</tt> is one of:
 +
* <tt>C
 +
* CPP
 +
* LD
 +
* LIB
 +
* WINDRES
 +
* MAKE</tt>
 +
it will be replaced with the name of the corresponding executable.
 +
 +
True if <tt>regex</tt> matches the command's output (in this case, version number <tt>>=</tt> 4.3.0).
 +
 +
<tt>default</tt> is used if the command fails to execute (optional).
 +
 +
 +
If the output of the exec command is easily parseable (p.e. GCC-9.1.0 will output 9.1.0) there are more handy tests for numeric comparison:
 +
<source lang="xml" enclose="div">
 +
<if exec="C -dumpversion"
 +
    test="9.1.3"
 +
    default="true">
 +
[...]
 +
</if>
 +
</source>
 +
where ''test'' can be one of:
  
 +
* version_greater
 +
* version_greater_equal
 +
* version_equal
 +
* version_not_equal
 +
* version_less_equal
 +
* version_less
  
 +
If the output is not so easy to parse, as it happens p.e. with "sdcc --version", there is an extended version of the regex test (since r12739) allowing version extraction followed by numeric comparison:<source lang="xml" enclose="div">
 +
<if exec="C --version"
 +
    regex="([0-9]+\.[0-9]+\.[0-9]+);op;a.b.c"
 +
    default="true">
 +
[...]
 +
</if>
 +
</source>
 +
The capturing regex is followed by an operator and a version number in a.b.c format (not limited to three parts). The separator is a semicolon, if the regex includes one it can be escaped with a backslash. The operator (op) can be one of:
 +
 +
* gt: greater than
 +
* ge: greater or equal
 +
* eq: equal
 +
* ne: not equal
 +
* le: less or equal
 +
* lt: less than
 +
 +
All these tests can be cascaded, and the result will be the logical AND of the individual results (with short circuit, so a ''false'' will skip the remaining tests).:<source lang="xml" enclose="div">
 +
<if exec="C -dumpversion"
 +
    version_greater_equal="9.1.3"
 +
    version_less="11.0"
 +
    default="true">
 +
[...]
 +
</if>
 +
</source>
 
<source lang="xml" enclose="div">
 
<source lang="xml" enclose="div">
 
<Program name="C" value="mingw32-gcc.exe"/>
 
<Program name="C" value="mingw32-gcc.exe"/>
Line 44: Line 113:
 
* CPP
 
* CPP
 
* LD
 
* LD
* DBG
 
 
* DBGconfig
 
* DBGconfig
 
* LIB
 
* LIB
Line 179: Line 247:
  
 
The contents is the regex (use of a <tt>CDATA</tt> section is not required).
 
The contents is the regex (use of a <tt>CDATA</tt> section is not required).
 +
 +
==Proposed Updates==
 +
See: [https://forums.codeblocks.org/index.php/topic,19032.0.html Use wxPropGrid for compiler flags]
 +
 +
<source lang="xml" enclose="div" highlight="3-5">
 +
<Option name="Intel Pentium (MMX)"
 +
        option="-march=pentium-mmx"
 +
        type="string"
 +
        default="pentium-mmx"
 +
        compose="-march=$(ENTRY)"/>
 +
</source>
 +
For <tt>type="string"</tt>, a free text editor is presented.
 +
 +
<tt>default="</tt><str><tt>"</tt>. <str> is the default text for the editor textbox.
 +
 +
<tt>compose="</tt><str><tt>"</tt>. <str> is the template for generating the compile command. All occurrences of <tt>$(ENTRY)</tt> are replaced with the content of the textbox. (Extensions: all occurrences of <tt>$(ENTRY_QUOTE)</tt> are replaced with the content of the textbox, and quoted/escaped as needed; <tt>$(ENTRY_STRIP)</tt> is replaced with the textbox content, all whitespace removed.)
 +
 +
 +
<source lang="xml" enclose="div" highlight="4-10">
 +
<Option name="Link time optimization"
 +
        option="-flto"
 +
        additionalLibs="-flto -O2"
 +
        type="integer"
 +
        default="1"
 +
        min="1"
 +
        max="16"
 +
        label="Parallel link jobs"
 +
        compose="-flto"
 +
        composeLib="-flto=$(ENTRY) -02"/>
 +
</source>
 +
For <tt>type="integer"</tt>, a spin dial is presented.
 +
 +
<tt>default="</tt><int><tt>"</tt>. <int> is the starting value.
 +
 +
<tt>min="</tt><int><tt>"</tt>. <int> the minimum allowed value.
 +
 +
<tt>max="</tt><int><tt>"</tt>. <int> the maximum allowed value.
 +
 +
<tt>label="</tt><str><tt>"</tt>. <str> descriptive information (displayed as a tooltip? or maybe a label next to it?).
 +
 +
<tt>compose="</tt><str><tt>"</tt>. <str> is the template for generating the compile command. All occurrences of <tt>$(ENTRY)</tt> are replaced with the value of the spin control.
 +
 +
<tt>composeLib="</tt><str><tt>"</tt>. <str> is the template for generating the link command. All occurrences of <tt>$(ENTRY)</tt> are replaced with the value of the spin control.
 +
 +
 +
<source lang="xml" enclose="div" highlight="3">
 +
<Option name="Intel i386"
 +
        option="-march=i386"
 +
        type="boolean"/>
 +
</source>
 +
For <tt>type="boolean"</tt>, a standard checkbox is supplied (this is default behavior if no <tt>type</tt> is specified).
 +
 +
 +
<source lang="xml" enclose="div" highlight="2,5-7">
 +
<Combo comboId="architecture"
 +
      label="Generate code for:"/>
 +
<Option name="Generate code for Intel i386"
 +
        option="-march=i386"
 +
        type="combo"
 +
        comboId="architecture"
 +
        label="Intel i386"/>
 +
</source>
 +
<tt><Combo [...]/></tt> defines a combo select box with <tt>label="</tt><str><tt>"</tt>.
 +
 +
For <tt>type="combo"</tt>, an entry is added to a combo select box.
 +
 +
<tt>comboId="</tt><str><tt>"</tt>. <str> is the id of the combo box to add this command to.
 +
 +
<tt>label="</tt><str><tt>"</tt>. <str> is the text to name this entry in the combo box's list. (If not supplied, <tt>name="</tt><str><tt>"</tt> is used instead.)
 +
 +
 +
All of these proposed changes maintain both forwards and backwards compatibility. The new attributes will be ignored by older versions of Code::Blocks. Any entry which does not contain the required fields for this updated format can be rendered as <tt>type="boolean"</tt> to read older files, with no loss of information. [[User:Alpha|Alpha]] 01:59, 25 June 2014 (CEST)
 +
 +
==See also==
 +
* [[Compiler file]]
 +
* [https://forums.codeblocks.org/index.php/topic,16463.0.html XML based compilers]

Latest revision as of 13:25, 7 March 2022

Format for storing compiler options in editable XML.


<CodeBlocks_compiler_options extends="gcc">
[...]
</CodeBlocks_compiler_options>

I am a Code::Blocks compiler options file.

extends="<id>" (optional)

  • Load the corresponding options_<id>.xml file first (use if this compiler is almost the same, with only a few altered programs or added switches, for example).


<if platform="windows">
[...]
</if>
<else>
[...]
</else>

Standard if statement; contents of if block is evaluated if the if statement is true, otherwise the else block is evaluated (the else block is optional). Nesting is allowed.

platform="<os>". <os> is one of:

  • windows
  • macosx
  • linux
  • freebsd
  • netbsd
  • openbsd
  • darwin
  • solaris
  • unix
<if exec="bison -h">
[...]
</if>

True if the the command exec can be run.

<if exec="C -dumpversion"
    regex="^4\.[3-9]|^[5-9]\.[0-9]"
    default="true">
[...]
</if>

If the text before the first space in exec is one of:

  • C
  • CPP
  • LD
  • LIB
  • WINDRES
  • MAKE

it will be replaced with the name of the corresponding executable.

True if regex matches the command's output (in this case, version number >= 4.3.0).

default is used if the command fails to execute (optional).


If the output of the exec command is easily parseable (p.e. GCC-9.1.0 will output 9.1.0) there are more handy tests for numeric comparison:

<if exec="C -dumpversion"
    test="9.1.3"
    default="true">
[...]
</if>

where test can be one of:

  • version_greater
  • version_greater_equal
  • version_equal
  • version_not_equal
  • version_less_equal
  • version_less

If the output is not so easy to parse, as it happens p.e. with "sdcc --version", there is an extended version of the regex test (since r12739) allowing version extraction followed by numeric comparison:

<if exec="C --version"
    regex="([0-9]+\.[0-9]+\.[0-9]+);op;a.b.c"
    default="true">
[...]
</if>

The capturing regex is followed by an operator and a version number in a.b.c format (not limited to three parts). The separator is a semicolon, if the regex includes one it can be escaped with a backslash. The operator (op) can be one of:

  • gt: greater than
  • ge: greater or equal
  • eq: equal
  • ne: not equal
  • le: less or equal
  • lt: less than

All these tests can be cascaded, and the result will be the logical AND of the individual results (with short circuit, so a false will skip the remaining tests).:

<if exec="C -dumpversion"
    version_greater_equal="9.1.3"
    version_less="11.0"
    default="true">
[...]
</if>
<Program name="C" value="mingw32-gcc.exe"/>

Give the name of an executable

name="<prog>". <prog> is one of:

  • C
  • CPP
  • LD
  • DBGconfig
  • LIB
  • WINDRES
  • MAKE

value="<exec>" (actual name of the executable).


<Switch name="includeDirs" value="-I"/>

Switches controlling compiler constants.

name="<opt>". <opt> is one of:

  • includeDirs
  • libDirs
  • linkLibs
  • defines
  • genericSwitch
  • objectExtension
  • forceFwdSlashes. value is one of true or false
  • forceLinkerUseQuotes. value is one of true or false
  • forceCompilerUseQuotes. value is one of true or false
  • needDependencies. value is one of true or false
  • logging. value is one of:
    • default (same as full)
    • full
    • simple
    • none
  • libPrefix
  • libExtension
  • linkerNeedsLibPrefix. value is one of true or false
  • linkerNeedsLibExtension. value is one of true or false
  • supportsPCH. value is one of true or false
  • PCHExtension
  • UseFlatObjects. value is one of true or false
  • UseFullSourcePaths. value is one of true or false
  • Use83Paths. value is one of true or false


<Option name="Profile code when executed"
        option="-pg"
        additionalLibs="-pg -lgmon"
        category="Profiling"
        checkAgainst="-O -O1 -O2 -O3 -Os"
        checkMessage="You have optimizations enabled. This is Not A Good Thing(tm) when producing debugging symbols..."
        supersedes="-s"
        exclusive="true"/>

Definition of a compiler flag.

  • name. Human readable description of the flag.
  • option. Flags to be sent to the compiler (optional).
  • additionalLibs. Flags to be sent to the linker (optional).
  • category. The category this flag is in (optional; defaults to "General").
  • checkAgainst. Show a warning message if any of these flags are enabled (optional).
  • checkMessage. Warning message to show upon conflict (optional).
  • superseds. Automatically disable the list of superseded flags if this flag is enabled (optional).
  • exclusive. Disable all other flags in this category if this flag is enabled. Is one of true or false (optional).


<Category name="CPU architecture tuning"
          exclusive="true">
[...]
</Category>

name="<cat>". Any flags (<Option [...] />) contained in here that lack the category attribute will be treated as category <cat>.

exclusive. Is one of true or false. Any flags (<Option [...] />) contained in here that lack the exclusive attribute will be treated as this. (Optional.)


<Common name="optimization"/>

Load options from a common file.

name="<file>"

  • Loads options_common_<file>.xml (file syntax is exactly the same as this file).


<Command name="CompileObject"
         value="$compiler $options $includes -c $file -o $object"/>

Definitions for forming compiler commands.

name="<cmd>". <cmd> is one of:

  • CompileObject
  • GenDependencies
  • CompileResource
  • LinkExe
  • LinkConsoleExe
  • LinkDynamic
  • LinkStatic
  • LinkNative
<Command name="CompileObject"
         value="bison -v -d $file -o $file_dir/$file_name.parser.cc"
         ext="y"
         gen="$file_dir/$file_name.parser.cc;$file_dir/$file_name.parser.hh"/>

Additional commands can be added to each category with a file extension filter.

ext="<exts>". <exts> is a semicolon separated list of file extensions (without the leading "." period).

gen="<files>". <files> is a semicolon separated list of generated files to be further processed (optional).


<RegEx name="Info line"
       type="info"
       msg="1;2;4"
       file="2"
       line="3">
    <![CDATA[(In file) ([][{}() \t#%$~[:alnum:]&_:+/\.-]+):([0-9]+)(\.[0-9]+.*:)*]]>
</RegEx>

Definitions for regular expressions to parse compiler output.

name="<label>". <label> is the name this regex will be listed as.

type="<tp>". <tp> is one of

  • normal
  • warning
  • error
  • info

msg="<nums>". <nums> is a semicolon separated list of indices (minimum one, maximum three) for the locations of messages within the regex.

file="<num>". <num> is the index of the regex which gives the relevant file (optional).

line="<num>". <num> is the index of the regex which gives the relevant line number (optional).

The contents is the regex (use of a CDATA section is not required).

Proposed Updates

See: Use wxPropGrid for compiler flags

<Option name="Intel Pentium (MMX)"
        option="-march=pentium-mmx"
        type="string"
        default="pentium-mmx"
        compose="-march=$(ENTRY)"/>

For type="string", a free text editor is presented.

default="<str>". <str> is the default text for the editor textbox.

compose="<str>". <str> is the template for generating the compile command. All occurrences of $(ENTRY) are replaced with the content of the textbox. (Extensions: all occurrences of $(ENTRY_QUOTE) are replaced with the content of the textbox, and quoted/escaped as needed; $(ENTRY_STRIP) is replaced with the textbox content, all whitespace removed.)


<Option name="Link time optimization"
        option="-flto"
        additionalLibs="-flto -O2"
        type="integer"
        default="1"
        min="1"
        max="16"
        label="Parallel link jobs"
        compose="-flto"
        composeLib="-flto=$(ENTRY) -02"/>

For type="integer", a spin dial is presented.

default="<int>". <int> is the starting value.

min="<int>". <int> the minimum allowed value.

max="<int>". <int> the maximum allowed value.

label="<str>". <str> descriptive information (displayed as a tooltip? or maybe a label next to it?).

compose="<str>". <str> is the template for generating the compile command. All occurrences of $(ENTRY) are replaced with the value of the spin control.

composeLib="<str>". <str> is the template for generating the link command. All occurrences of $(ENTRY) are replaced with the value of the spin control.


<Option name="Intel i386"
        option="-march=i386"
        type="boolean"/>

For type="boolean", a standard checkbox is supplied (this is default behavior if no type is specified).


<Combo comboId="architecture"
       label="Generate code for:"/>
<Option name="Generate code for Intel i386"
        option="-march=i386"
        type="combo"
        comboId="architecture"
        label="Intel i386"/>

<Combo [...]/> defines a combo select box with label="<str>".

For type="combo", an entry is added to a combo select box.

comboId="<str>". <str> is the id of the combo box to add this command to.

label="<str>". <str> is the text to name this entry in the combo box's list. (If not supplied, name="<str>" is used instead.)


All of these proposed changes maintain both forwards and backwards compatibility. The new attributes will be ignored by older versions of Code::Blocks. Any entry which does not contain the required fields for this updated format can be rendered as type="boolean" to read older files, with no loss of information. Alpha 01:59, 25 June 2014 (CEST)

See also