Difference between revisions of "Using GDC"

From D Wiki
Jump to: navigation, search
m
m (Attributes: - use gcc.attributes instead of deprecated "attribute" module)
 
(37 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{ParentArticle| [[GDC]]}}
 
  
= User Documentation =
+
== Simple Compilation ==
== Usage of GDC ==
 
 
 
=== Simple Compilation ===
 
  
 
Creating an executable is quite easy.
 
Creating an executable is quite easy.
Line 17: Line 13:
 
On a typical Unix system, you can execute the resulting program with "./main" or "./a.out". On Windows, you can run the program with "main" or "a.out".(?)
 
On a typical Unix system, you can execute the resulting program with "./main" or "./a.out". On Windows, you can run the program with "main" or "a.out".(?)
  
To help make a transition from DMD to GDC easier, there is a script called 'gdmd' which maps
+
To help make a transition from [[DMD]] to [[GDC]] easier, there is the standalone program 'gdmd', distributed with GDC releases, which maps DMD's command line options to GDC.
DMD's command line options to GDC. To see the available options for gdmd, type 'gdmd' or
+
To see the available options for gdmd, type 'gdmd' or 'gdmd -help' on the command line.
'gdmd -help' on the command line.
 
  
 
----
 
----
Line 25: Line 20:
 
== Command line switches ==
 
== Command line switches ==
  
A list of the available command line switches in GDC:
+
You can always display a list of D-specific command line switches with:
 +
 
 +
<syntaxhighlight lang="bash">
 +
gdc --help=d
 +
</syntaxhighlight>
  
{|
+
Many of the options in GCC may also be applicable to GDC, such as optimization flags, -O1, -O2, -Os, -O3, or flags such as -c, which compiles a file, but does not link it, and will send the object file to "main.o", if your file is main.d
! align="left"| Switch
+
 
! align="left"| Description
+
==== Compiler Options ====
 +
 
 +
{|class="wikitable"
 +
! Switch
 +
! Description
 
|-
 
|-
| -I<dir>||Add <dir> to the end of the main include path.
+
| '''-debuglib='''<lib>||Link against a debug <lib> instead of Phobos.
 
|-
 
|-
| -J<dir>||Add <dir> to the end of the string import path.
+
| '''-defaultlib='''<lib>||Link against <lib> instead of Phobos.
 
|-
 
|-
| -fdeprecated||Allow use of deprecated features.
+
| '''-fdeps'''||Print information about module dependencies.
 
|-
 
|-
| -fassert||Generate runtime code for assert()'s
+
| '''-fdeps='''<file>||Write module dependencies to <file>.
 
|-
 
|-
| -frelease||Compile release version
+
| '''-fdoc'''||Generate Ddoc documentation.
 
|-
 
|-
| -f[no-]bounds-check||Controls array bounds checking
+
| '''-fdoc-dir='''<dir>||Write Ddoc documentation files to <dir>.
 
|-
 
|-
| -funittest||Compile in unittest code
+
| '''-fdoc-file='''<file>||Write Ddoc documentation to <file>.
 
|-
 
|-
| -fversion=<level/ident>||Compile in version code >= <level> or identified by <ident>
+
| '''-fdoc-inc='''<file>||Include a Ddoc macro <file>.
 
|-
 
|-
| -fdebug,-fdebug=<level>,-fdebug=<ident>||Compile in debug code, code <= level, or code identified by ident
+
| '''-fintfc'''||Generate D interface files,
 
|-
 
|-
| -fdebug||Compile in debug code
+
| '''-fintfc-dir='''<dir>||Write D interface files to directory <dir>.
 
|-
 
|-
| -fdebug-c||With -g, generate C debug information for debugger compatibility
+
| '''-fintfc-file='''<file>||Write D interface file to <file>.
 
|-
 
|-
| -fdeps=<filename>||Write module dependencies to filename
+
| '''-fmake-deps'''||Print information about module Makefile dependencies.
 
|-
 
|-
| -fd-verbose||Print information about D language processing to stdout
+
| '''-fmake-deps='''<file>||Write Makefile dependency output to <file>.
 
|-
 
|-
| -fd-version=1||Compile as D language version 1
+
| '''-fmake-mdeps'''||Like -fmake-deps but ignore system modules.
 
|-
 
|-
| -f[no-]emit-templates||Controls whether or not template code is emitted.
+
| '''-fmake-mdeps='''<file>||Like -fmake-deps=<file> but ignore system modules.
 
|-
 
|-
| -fall-sources||For each source file on the command line, semantically process each file preceding it. Use this if compilation errors occur due to complicated circular module references. This will slow compilation noticeably
+
| '''-fonly='''<file>||Process all modules specified on the command line, but only generate code for the module <file>.
 
|-
 
|-
| -nostdinc||Do not search standard system include directories
+
| '''-fXf='''<file>|| Write JSON documenation to <file>.
 
|-
 
|-
| -fonly=||Process all modules specified on the command line, but only generate code for the module specified by the argument.
+
| '''-imultilib''' <dir>||Set <dir> to be the multilib include subdirectory.
 
|-
 
|-
| -fod=<directory>||Specify the object output directory. Note: this is actually a driver option; the backend ignores it.
+
| '''-iprefix''' <path>||Specify <path> as a prefix for next two options.
 
|-
 
|-
| -fop||Specify that the source file's parent directories should be appended to the object output directory. Note: this is actually a driver option; the backend ignores it.
+
| '''-isysroot''' <dir>||Set <dir> to be the system root directory.
 
|-
 
|-
| -fignore-unknown-pragmas||Ignore unsupported pragmas
+
| '''-isystem''' <dir>||Add <dir> to the start of the system include path.
 
|-
 
|-
| -fintfc||Generate D interface files
+
| '''-I''' <dir>||Add <dir> to the list of the module import paths.
 
|-
 
|-
| -fintfc-dir=<dir>||Write D interface files to directory <dir>
+
| '''-J''' <dir>||Add <dir> to the list of string import paths.
 
|-
 
|-
| -fintfc-file=<filename>||Write D interface file to <filename>
+
| '''-nophoboslib'''||Do not link the standard D library in the compilation.  The D standard library, Phobos, and the D runtime are compiled into a single library, libgphobos2.  Therefore, this option prevents linking both Phobos and the D runtime.
 
|-
 
|-
| -fdoc||Generate documentation
+
| '''-nostdinc'''||Do not search standard system include directories.
 
|-
 
|-
| -fdoc-dir=<docdir>||Write documentation file to docdir directory
+
| '''-nostdlib'''||Do not link the standard gcc libraries in the compilation.
 +
|}
 +
 
 +
==== Language Options ====
 +
 
 +
Most of these have both positive and negative forms; the negative form of '''-ffoo''' is '''-fno-foo'''.
 +
This page lists only one of these two forms, whichever one is not the default.
 +
 
 +
{|class="wikitable"
 +
! Switch
 +
! Description
 +
|-
 +
| '''-fno-assert'''||Don't generate runtime code for the <code>assert</code> keyword.
 
|-
 
|-
| -fdoc-file=<filename>||Write documentation file to filename
+
| '''-fno-bounds-check'''||Don't generate runtime code for checking array bounds before indexing.
 
|-
 
|-
| -fdoc-inc=<filename>||Include a Ddoc macro file
+
| '''-fno-builtin'''||Don't recognize built-in functions. It only goes as far as not recognizing user declared functions as being built-in.  The compiler may still generate builtin calls internally.
 
|-
 
|-
| -fmultilib-dir=<dir>||Select header multilib subdirectory
+
| '''-fno-debug'''||Don't compile <code>debug</code> code.
 
|-
 
|-
| -Wsign-compare||Warn about signed-unsigned comparisons
+
| '''-fdebug='''<level>||Compile in debug code less than or equal to that in <level>.
 
|-
 
|-
| -fdump-source||Dump decoded UTF-8 text and source from HTML to <file>.utf-8 and <file>.d.utf-8
+
| '''-fdebug='''<ident>||Compile in debug code identified by <ident>.
 
|-
 
|-
| -fbuiltin||Recognize built-in functions
+
| '''-fd-verbose'''||Print information about D language processing to stdout.
 
|-
 
|-
| -funsigned-char||Make "char" unsigned by default (silently ignored in D)
+
| '''-fd-vtls'''||Print information about all variables going into thread local storage to stdout.
 
|-
 
|-
| -fsigned-char||Make "char" signed by default (silently ignored in D)
+
| '''-fall-instantiations'''||Generate code for all template instantiations, not just used instantiations.
 
|-
 
|-
| -iprefix <path>||Specify <path> as a prefix for next two options
+
| '''-fno-in'''||Don't compile <code>in</code> contracts.
 
|-
 
|-
| -isysroot <dir>||Set <dir> to be the system root directory
+
| '''-fno-invariants'''||Don't compile <code>invariant</code> contracts.
 
|-
 
|-
| -isystem <dir>||Add <dir> to the start of the system include path
+
| '''-fno-emit-moduleinfo'''||Don't generate any <code>ModuleInfo</code>.
 
|-
 
|-
| -Wall||Enable most warning messages
+
| '''-fno-out'''||Don't compile <code>out</code> contracts.
 
|-
 
|-
| -Werror||Error out the compiler on warnings
+
| '''-fproperty'''||Enforce @property syntax of D code.
 +
|-
 +
| '''-frelease'''||Compile release version.  Equivalent to -fno-invariants -fno-in -fno-out -fno-assert -fno-bounds-check.
 +
|-
 +
| '''-funittest'''||Compile <code>unittest</code> code.
 +
|-
 +
| '''-fversion='''<level>||Compile in version code greater than or equal to that in <level>.
 +
|-
 +
| '''-fversion='''<ident>||Compile in version code identified by <ident>.
 +
|-
 +
| '''-Wall'''||Enable most warning messages.
 +
|-
 +
| '''-Werror'''||Error out the compiler on warnings.
 +
|-
 +
| '''-Wdeprecated'''||Enable warning of deprecated language features.
 +
|-
 +
| '''-Wunknown-pragmas'''||Enable warning of unsupported pragmas.
 
|}
 
|}
  
 
Many of the options in GCC may also be applicable to GDC, such as optimization flags, -O1, -O2, -Os, -O3, or flags such as -c, which compiles a file, but does not link it, and will send the object file to "main.o", if you file is main.d
 
  
 
----
 
----
Line 119: Line 148:
 
GDC implements a GCC extension that allows inline assembler with D expression operands.  It is available on nearly all targets, not just i386.  The syntax differs from the C language extension in the following ways:  
 
GDC implements a GCC extension that allows inline assembler with D expression operands.  It is available on nearly all targets, not just i386.  The syntax differs from the C language extension in the following ways:  
 
* Statements start with 'asm { ...', just like the regular DMD inline assembler.
 
* Statements start with 'asm { ...', just like the regular DMD inline assembler.
* It is not necesary to put parentheses around operands.
 
 
* Instruction templates can be compile-time string constants, not just string literals.  If the template is not a string literal, use parenthesis to indicate that it is not an opcode.
 
* Instruction templates can be compile-time string constants, not just string literals.  If the template is not a string literal, use parenthesis to indicate that it is not an opcode.
  
Line 132: Line 160:
 
     uint result;
 
     uint result;
 
     version(X86)
 
     version(X86)
       asm{ "notl %[iov]" : [iov] "=r" result : "0" v; }
+
       asm{ "notl %[iov]" : [iov] "=r" (result) : "0" (v); }
 
     else version(PPC)
 
     else version(PPC)
       asm{ "nor %[oresult],%[iv],%[iv]" : [oresult] "=r" result : [iv] "r" v; }
+
       asm{ "nor %[oresult],%[iv],%[iv]" : [oresult] "=r" (result) : [iv] "r" (v); }
 
     return result;
 
     return result;
 
}
 
}
 +
</syntaxhighlight>
 +
 +
=== Attributes ===
 +
GDC supports a small subset of the [http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC attributes]. The syntax differs from the C language __attribute__ extension in the following ways:
 +
 +
* All attributes are recognised only through the 'gcc.attributes' module.
 +
* The attribute, and all its arguments are comma-delimited CTFE strings packed in a tuple.
 +
* Nesting (brackets) for attribute arguments are optional.
 +
 +
 +
{|class="wikitable"
 +
! Attribute
 +
! Description
 +
|-
 +
| forceinline* || Inlines the function even if no optimization level is specified.
 +
|-
 +
| flatten* || Inlines every call inside this function, if possible.
 +
|-
 +
| noinline* || Prevents the function from being considered for inlining.
 +
|-
 +
| target* || Specify that the function is to be compiled with different target options than specified on the command line.
 +
|-
 +
| noclone* || See [http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html GCC documentation].
 +
|-
 +
| section* || Place symbol in specific section. See [http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html GCC documentation].
 +
|-
 +
| weak* || Mark symbol as weak. See [http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html GCC documentation].
 +
|-
 +
| alias* || Mark symbol as an alias (on object file level). See [http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html GCC documentation].
 +
|-
 +
| architecture specific attributes || All target specific attributes are available. See [http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html GCC documentation].
 +
|}
 +
 +
<nowiki>*</nowiki> Being backend attributes, you can't enforce that these attributes actually take effect in user code (no static asserts!) - but you have some guarantee in that the backend will complain if it can't apply the attribute
 +
 +
 +
Example:
 +
<syntaxhighlight lang="D">
 +
import gcc.attributes;
 +
 +
@attribute("noinline") void foobar() { }
 +
 +
@attribute("target", ("sse3")) void sse3_func() { }
 +
 +
//Can be overwritten in other source files
 +
@attribute("weak") extern(C) void c_func() {};
 +
@attribute("alias", "c_func") void aliased_func();
 +
 +
//Place into "test" section
 +
@attribute("section", "test") int value;
 +
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== Known Issues ==
 
== Known Issues ==
  
See our [//bitbucket.org/goshawk/gdc/issues?status=new&status=open issue tracker] to see
+
See [http://bugzilla.gdcproject.org bugzilla] to see
 
bugs that have been reported to GDC.
 
bugs that have been reported to GDC.
 
More bugs may be found [//d.puremagic.com/issues/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__open__&product=DGCC+aka+GDC&content= here].
 
  
 
Some more known issues, taken from [//dgcc.sourceforge.net/gdc/manual.html here]:
 
Some more known issues, taken from [//dgcc.sourceforge.net/gdc/manual.html here]:
  
* See the [//svn.kuehne.cn/dstress/www/dstress.html DStress page] for known failing cases.
+
* See [http://dstress.kuehne.cn/www/dstress.html DStress] for known failing cases. (Again, may be irrelevant)
(Again, may be irrelevant)
 
 
* Debugging information may have a few problems. For D symbol name demangling you need at least gdb 7.2.
 
* Debugging information may have a few problems. For D symbol name demangling you need at least gdb 7.2.
* Some targets do not support once-only linking. A workaround is to manually control template emission.  
+
* Some targets do not support once-only linking. A workaround is to manually control template emission.   See the -fall-instantiations (-femit-templates in old GDC versions) option above. For Darwin, Apple's GCC 3.x compiler supports one-only linking, but GDC does not build with those sources. There are no problems with the stock GCC 4.x on Darwin.
See the -femit-templates option below. For Darwin, Apple's GCC 3.x compiler supports one-only linking,  
 
but GDC does not build with those sources. There are no problems with the stock GCC 4.x on Darwin.
 
 
* Complex floating point operations may not work the same as DMD.
 
* Complex floating point operations may not work the same as DMD.
 
* Some math functions behave differently due to different implementations of the extended floating-point type.
 
* Some math functions behave differently due to different implementations of the extended floating-point type.
 
* Volatile statements may not always do the right thing.
 
* Volatile statements may not always do the right thing.
* Because of [//groups-beta.google.com/groups?hl=en&q=%22large+executables+on+AIX%22&qt_s=Search a problem on AIX],
+
* Because of [//groups-beta.google.com/groups?hl=en&q=%22large+executables+on+AIX%22&qt_s=Search a problem on AIX], the linker will pull in more modules than needed.
the linker will pull in more modules than needed.
 
 
* Some C libraries (Cygwin, MinGW, AIX) don't handle floating-point formatting and parsing in a standard way.
 
* Some C libraries (Cygwin, MinGW, AIX) don't handle floating-point formatting and parsing in a standard way.
 +
 +
== See also ==
 +
* [[GDC]]
 +
 +
== External links ==
 +
*[https://github.com/D-Programming-GDC/GDMD GDMD Perl source]
 +
*[https://github.com/D-Programming-GDC/GDMD/tree/dport GDMD D version]
 +
 +
[[Category:GDC Compiler]]

Latest revision as of 16:07, 9 June 2022

Simple Compilation

Creating an executable is quite easy.

gdc main.d -o main

This will attempt to compile and link the file 'main.d' and place the output into the file 'main'. If you do not use the -o switch, then your executable will be called 'a.out'.

On a typical Unix system, you can execute the resulting program with "./main" or "./a.out". On Windows, you can run the program with "main" or "a.out".(?)

To help make a transition from DMD to GDC easier, there is the standalone program 'gdmd', distributed with GDC releases, which maps DMD's command line options to GDC. To see the available options for gdmd, type 'gdmd' or 'gdmd -help' on the command line.


Command line switches

You can always display a list of D-specific command line switches with:

gdc --help=d

Many of the options in GCC may also be applicable to GDC, such as optimization flags, -O1, -O2, -Os, -O3, or flags such as -c, which compiles a file, but does not link it, and will send the object file to "main.o", if your file is main.d

Compiler Options

Switch Description
-debuglib=<lib> Link against a debug <lib> instead of Phobos.
-defaultlib=<lib> Link against <lib> instead of Phobos.
-fdeps Print information about module dependencies.
-fdeps=<file> Write module dependencies to <file>.
-fdoc Generate Ddoc documentation.
-fdoc-dir=<dir> Write Ddoc documentation files to <dir>.
-fdoc-file=<file> Write Ddoc documentation to <file>.
-fdoc-inc=<file> Include a Ddoc macro <file>.
-fintfc Generate D interface files,
-fintfc-dir=<dir> Write D interface files to directory <dir>.
-fintfc-file=<file> Write D interface file to <file>.
-fmake-deps Print information about module Makefile dependencies.
-fmake-deps=<file> Write Makefile dependency output to <file>.
-fmake-mdeps Like -fmake-deps but ignore system modules.
-fmake-mdeps=<file> Like -fmake-deps=<file> but ignore system modules.
-fonly=<file> Process all modules specified on the command line, but only generate code for the module <file>.
-fXf=<file> Write JSON documenation to <file>.
-imultilib <dir> Set <dir> to be the multilib include subdirectory.
-iprefix <path> Specify <path> as a prefix for next two options.
-isysroot <dir> Set <dir> to be the system root directory.
-isystem <dir> Add <dir> to the start of the system include path.
-I <dir> Add <dir> to the list of the module import paths.
-J <dir> Add <dir> to the list of string import paths.
-nophoboslib Do not link the standard D library in the compilation. The D standard library, Phobos, and the D runtime are compiled into a single library, libgphobos2. Therefore, this option prevents linking both Phobos and the D runtime.
-nostdinc Do not search standard system include directories.
-nostdlib Do not link the standard gcc libraries in the compilation.

Language Options

Most of these have both positive and negative forms; the negative form of -ffoo is -fno-foo. This page lists only one of these two forms, whichever one is not the default.

Switch Description
-fno-assert Don't generate runtime code for the assert keyword.
-fno-bounds-check Don't generate runtime code for checking array bounds before indexing.
-fno-builtin Don't recognize built-in functions. It only goes as far as not recognizing user declared functions as being built-in. The compiler may still generate builtin calls internally.
-fno-debug Don't compile debug code.
-fdebug=<level> Compile in debug code less than or equal to that in <level>.
-fdebug=<ident> Compile in debug code identified by <ident>.
-fd-verbose Print information about D language processing to stdout.
-fd-vtls Print information about all variables going into thread local storage to stdout.
-fall-instantiations Generate code for all template instantiations, not just used instantiations.
-fno-in Don't compile in contracts.
-fno-invariants Don't compile invariant contracts.
-fno-emit-moduleinfo Don't generate any ModuleInfo.
-fno-out Don't compile out contracts.
-fproperty Enforce @property syntax of D code.
-frelease Compile release version. Equivalent to -fno-invariants -fno-in -fno-out -fno-assert -fno-bounds-check.
-funittest Compile unittest code.
-fversion=<level> Compile in version code greater than or equal to that in <level>.
-fversion=<ident> Compile in version code identified by <ident>.
-Wall Enable most warning messages.
-Werror Error out the compiler on warnings.
-Wdeprecated Enable warning of deprecated language features.
-Wunknown-pragmas Enable warning of unsupported pragmas.



Extensions

Extended Assembler

GDC implements a GCC extension that allows inline assembler with D expression operands. It is available on nearly all targets, not just i386. The syntax differs from the C language extension in the following ways:

  • Statements start with 'asm { ...', just like the regular DMD inline assembler.
  • Instruction templates can be compile-time string constants, not just string literals. If the template is not a string literal, use parenthesis to indicate that it is not an opcode.

Unlike i386 inline assembler statements, extended assembler statements do not prevent a function from being inlined.

See the GCC manual for more information about this extension.

Example:

uint invert(uint v)
{
    uint result;
    version(X86)
       asm{ "notl %[iov]" : [iov] "=r" (result) : "0" (v); }
    else version(PPC)
       asm{ "nor %[oresult],%[iv],%[iv]" : [oresult] "=r" (result) : [iv] "r" (v); }
    return result;
}

Attributes

GDC supports a small subset of the GCC attributes. The syntax differs from the C language __attribute__ extension in the following ways:

  • All attributes are recognised only through the 'gcc.attributes' module.
  • The attribute, and all its arguments are comma-delimited CTFE strings packed in a tuple.
  • Nesting (brackets) for attribute arguments are optional.


Attribute Description
forceinline* Inlines the function even if no optimization level is specified.
flatten* Inlines every call inside this function, if possible.
noinline* Prevents the function from being considered for inlining.
target* Specify that the function is to be compiled with different target options than specified on the command line.
noclone* See GCC documentation.
section* Place symbol in specific section. See GCC documentation.
weak* Mark symbol as weak. See GCC documentation.
alias* Mark symbol as an alias (on object file level). See GCC documentation.
architecture specific attributes All target specific attributes are available. See GCC documentation.

* Being backend attributes, you can't enforce that these attributes actually take effect in user code (no static asserts!) - but you have some guarantee in that the backend will complain if it can't apply the attribute


Example:

import gcc.attributes;

@attribute("noinline") void foobar() { }

@attribute("target", ("sse3")) void sse3_func() { }

//Can be overwritten in other source files
@attribute("weak") extern(C) void c_func() {};
@attribute("alias", "c_func") void aliased_func();

//Place into "test" section
@attribute("section", "test") int value;

Known Issues

See bugzilla to see bugs that have been reported to GDC.

Some more known issues, taken from here:

  • See DStress for known failing cases. (Again, may be irrelevant)
  • Debugging information may have a few problems. For D symbol name demangling you need at least gdb 7.2.
  • Some targets do not support once-only linking. A workaround is to manually control template emission. See the -fall-instantiations (-femit-templates in old GDC versions) option above. For Darwin, Apple's GCC 3.x compiler supports one-only linking, but GDC does not build with those sources. There are no problems with the stock GCC 4.x on Darwin.
  • Complex floating point operations may not work the same as DMD.
  • Some math functions behave differently due to different implementations of the extended floating-point type.
  • Volatile statements may not always do the right thing.
  • Because of a problem on AIX, the linker will pull in more modules than needed.
  • Some C libraries (Cygwin, MinGW, AIX) don't handle floating-point formatting and parsing in a standard way.

See also

External links