diff mbox

[4/13] D: The front-end (GDC) config, makefile, and manpages.

Message ID CABOHX+cEaoVt+y6TW3aB6m=o5-n6qvGAAgoBCSOo4HUOLJd7fA@mail.gmail.com
State New
Headers show

Commit Message

Iain Buclaw May 28, 2017, 9:12 p.m. UTC 
This patch adds the D frontend language configure make files, as
described on the anatomy of a language front-end.

---

Comments

Jeff Law Sept. 11, 2017, 4:05 p.m. UTC | #1 
On 05/28/2017 03:12 PM, Iain Buclaw wrote:
> This patch adds the D frontend language configure make files, as
> described on the anatomy of a language front-end.
> 
> ---
> 
> 
> 04-d-frontend-misc.patch
> 
> 


> +
> +You can specify more than one input file on the @command{gdc} command line,
> +in which case they will all be compiled.  If you specify a
> +@code{-o @var{file}} option, all the input files will be compiled together,
> +producing a single output file, named @var{file}.  This is allowed even
> +when using @code{-S} or @code{-c}.
So out of curiosity, when multiple sources are specified on the command
line, are they subject to IPA as a group or are they handled individually?

> +@item -fno-bounds-check
> +@cindex @option{-fbounds-check}
> +@cindex @option{-fno-bounds-check}
> +Turns off array bounds checking for all functions, which can improve
> +performance for code that uses array extensively.  Note that this
> +can result in unpredictable behavior if the code in question actually
> +does violate array bounds constraints.  It is safe to use this option
> +if you are sure that your code will never throw a @code{RangeError}.
So I don't know the internals of where you keep the bounds and how you
generate code for checking, but it might be worth looking at what Roger
Sayle did for Java array index checking back in 2016:

https://gcc.gnu.org/ml/java-patches/2016-q1/msg00014.html

I don't know if his trick of exposing an extra write would apply to D,
but it's worth reviewing.

> +
> +@item -funittest
> +@cindex @option{-funittest}
> +@cindex @option{-fno-unittest}
> +Turns on compilation of @code{unittest} code, and turns on the
> +@code{version(unittest)} identifier.  This implies @option{-fassert}.
I think we're using -fselftest elsewhere for unit testing bits within
the compiler.  Can you look and see if your unit tests are comparable
and perhaps consider using the same option if they are?


> +
> +@node Code Generation
> +@section Code Generation
> +@cindex options, code generation
> +
> +In addition to the many @command{gcc} options controlling code generation,
> +@command{gdc} has several options specific to itself.
> +
> +@table @gcctabopt
> +
> +@item -M
> +@cindex @option{-M}
> +Output the module dependencies of all source files being compiled in a
> +format suitable for @command{make}.  The compiler outputs one
> +@command{make} rule containing the object file name for that source file,
> +a colon, and the names of all imported files.
[ ... Many -M options ... ]
Note we recently allowed generation of the dependency files even in the
case some errors.  Please consider doing the same if it makes sense.
See the Sept change to c_common_finish.


> +
> +@c man begin ENVIRONMENT
> +
> +In addition to the many @command{gcc} environment variables that control
> +its operation, @command{gdc} has a few environment variables specific to
> +itself.
> +
> +@vtable @env
> +
> +@item D_IMPORT_PATH
> +@findex D_IMPORT_PATH
> +The value of @env{D_IMPORT_PATH} is a list of directories separated by a
> +special character, much like @env{PATH}, in which to look for imports.
> +The special character, @code{PATH_SEPARATOR}, is target-dependent and
> +determined at GCC build time.  For Microsoft Windows-based targets it is a
> +semicolon, and for almost all other targets it is a colon.
> +
> +@item DDOCFILE
> +@findex DDOCFILE
> +If @env{DDOCFILE} is set, it specifies a text file of macro definitions
> +to be read and used by the Ddoc generator.  This overrides any macros
> +defined in other @file{.ddoc} files.
How important are the environment variables to the existing user base?
We generally try to avoid changing much behavior based on environment
variables.  Can these be made command line options?

jeff
Iain Buclaw Sept. 11, 2017, 6:01 p.m. UTC | #2 
On 11 September 2017 at 18:05, Jeff Law <law@redhat.com> wrote:
> On 05/28/2017 03:12 PM, Iain Buclaw wrote:
>> This patch adds the D frontend language configure make files, as
>> described on the anatomy of a language front-end.
>>
>> ---
>>
>>
>> 04-d-frontend-misc.patch
>>
>>
>
>
>> +
>> +You can specify more than one input file on the @command{gdc} command line,
>> +in which case they will all be compiled.  If you specify a
>> +@code{-o @var{file}} option, all the input files will be compiled together,
>> +producing a single output file, named @var{file}.  This is allowed even
>> +when using @code{-S} or @code{-c}.
> So out of curiosity, when multiple sources are specified on the command
> line, are they subject to IPA as a group or are they handled individually?
>
>> +@item -fno-bounds-check
>> +@cindex @option{-fbounds-check}
>> +@cindex @option{-fno-bounds-check}
>> +Turns off array bounds checking for all functions, which can improve
>> +performance for code that uses array extensively.  Note that this
>> +can result in unpredictable behavior if the code in question actually
>> +does violate array bounds constraints.  It is safe to use this option
>> +if you are sure that your code will never throw a @code{RangeError}.
> So I don't know the internals of where you keep the bounds and how you
> generate code for checking, but it might be worth looking at what Roger
> Sayle did for Java array index checking back in 2016:
>
> https://gcc.gnu.org/ml/java-patches/2016-q1/msg00014.html
>
> I don't know if his trick of exposing an extra write would apply to D,
> but it's worth reviewing.
>

A dynamic array is a struct { size_t length, void* ptr }.  So if the
length was set in a place where the compiler can infer the value, then
it will be removed by the usual const propagation / dce passes.

Having a quick look, I am pretty sure that the code generation for D
is as such that, that particular case is handled without the extra
write - the length setting should already be exposed.

>> +
>> +@item -funittest
>> +@cindex @option{-funittest}
>> +@cindex @option{-fno-unittest}
>> +Turns on compilation of @code{unittest} code, and turns on the
>> +@code{version(unittest)} identifier.  This implies @option{-fassert}.
> I think we're using -fselftest elsewhere for unit testing bits within
> the compiler.  Can you look and see if your unit tests are comparable
> and perhaps consider using the same option if they are?
>

A unittest is a D language feature, D unittests are not compiled in by
default.  This turns them on.

Contrived example:

double pow2 (double x)
{
    return x ^^ 2;
}

unittest
{
    assert (pow2 (2) == 4);
}

>
>> +
>> +@node Code Generation
>> +@section Code Generation
>> +@cindex options, code generation
>> +
>> +In addition to the many @command{gcc} options controlling code generation,
>> +@command{gdc} has several options specific to itself.
>> +
>> +@table @gcctabopt
>> +
>> +@item -M
>> +@cindex @option{-M}
>> +Output the module dependencies of all source files being compiled in a
>> +format suitable for @command{make}.  The compiler outputs one
>> +@command{make} rule containing the object file name for that source file,
>> +a colon, and the names of all imported files.
> [ ... Many -M options ... ]
> Note we recently allowed generation of the dependency files even in the
> case some errors.  Please consider doing the same if it makes sense.
> See the Sept change to c_common_finish.
>

OK, thanks, I'll have a look.  The idea was to be closely resemble
C/C++, even though there is no preprocessor in D, and it outputs the
dependencies between module files.


>
>> +
>> +@c man begin ENVIRONMENT
>> +
>> +In addition to the many @command{gcc} environment variables that control
>> +its operation, @command{gdc} has a few environment variables specific to
>> +itself.
>> +
>> +@vtable @env
>> +
>> +@item D_IMPORT_PATH
>> +@findex D_IMPORT_PATH
>> +The value of @env{D_IMPORT_PATH} is a list of directories separated by a
>> +special character, much like @env{PATH}, in which to look for imports.
>> +The special character, @code{PATH_SEPARATOR}, is target-dependent and
>> +determined at GCC build time.  For Microsoft Windows-based targets it is a
>> +semicolon, and for almost all other targets it is a colon.
>> +
>> +@item DDOCFILE
>> +@findex DDOCFILE
>> +If @env{DDOCFILE} is set, it specifies a text file of macro definitions
>> +to be read and used by the Ddoc generator.  This overrides any macros
>> +defined in other @file{.ddoc} files.
> How important are the environment variables to the existing user base?
> We generally try to avoid changing much behavior based on environment
> variables.  Can these be made command line options?
>
> jeff

For D_IMPORT_PATH, there's -I /somedir, I wouldn't say that it needs
to be there, its just an equivalent of something that gcc exposes.

DDOCFILE I found in the DMD front-end implementation, and so thought
it best to say something about it.

Iain.
diff mbox

Patch

diff --git a/gcc/d/Make-lang.in b/gcc/d/Make-lang.in
new file mode 100644
index 00000000000..9618f5da8c0
--- /dev/null
+++ b/gcc/d/Make-lang.in
@@ -0,0 +1,274 @@ 
+# Make-lang.in -- Top level -*- makefile -*- fragment for the D frontend.
+# Copyright (C) 2006-2017 Free Software Foundation, Inc.
+
+# GCC is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+
+# GCC is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with GCC; see the file COPYING3.  If not see
+# <http://www.gnu.org/licenses/>.
+
+# This file provides the language dependent support in the main Makefile.
+
+# Installation name.
+
+D_INSTALL_NAME = $(shell echo gdc|sed '$(program_transform_name)')
+D_TARGET_INSTALL_NAME = $(target_noncanonical)-$(shell echo gdc|sed '$(program_transform_name)')
+
+# Name of phobos library
+D_LIBPHOBOS = -DLIBPHOBOS=\"gphobos\"
+
+# The name for selecting d in LANGUAGES.
+d: cc1d$(exeext)
+
+# Tell GNU make to ignore these if they exist.
+.PHONY: d
+
+# Create the compiler driver for D.
+CFLAGS-d/d-spec.o += $(DRIVER_DEFINES) $(D_LIBPHOBOS)
+
+GDC_OBJS = $(GCC_OBJS) d/d-spec.o
+gdc$(exeext): $(GDC_OBJS) $(EXTRA_GCC_OBJS) libcommon-target.a $(LIBDEPS)
+	+$(LINKER) $(ALL_LINKERFLAGS) $(LDFLAGS) -o $@ \
+	  $(GDC_OBJS) $(EXTRA_GCC_OBJS) libcommon-target.a \
+	  $(EXTRA_GCC_LIBS) $(LIBS)
+
+# Create a version of the gdc driver which calls the cross-compiler.
+gdc-cross$(exeext): gdc$(exeext)
+	-rm -f gdc-cross$(exeext)
+	cp gdc$(exeext) gdc-cross$(exeext)
+
+# Filter out pedantic and virtual overload warnings.
+d-warn = $(filter-out -pedantic -Woverloaded-virtual, $(STRICT_WARN))
+
+# D Frontend has slightly relaxed warnings compared to rest of GDC.
+DMD_WARN_CXXFLAGS = -Wno-deprecated -Wstrict-aliasing -Wuninitialized
+DMD_COMPILE = $(subst $(WARN_CXXFLAGS), $(DMD_WARN_CXXFLAGS), $(COMPILE))
+DMDGEN_COMPILE = $(subst $(COMPILER), $(COMPILER_FOR_BUILD), $(DMD_COMPILE))
+
+# D Frontend object files.
+D_FRONTEND_OBJS = \
+	d/argtypes.o d/aav.o d/access.o d/aliasthis.o d/apply.o d/arrayop.o \
+	d/attrib.o d/canthrow.o d/checkedint.o d/clone.o d/cond.o \
+	d/constfold.o d/cppmangle.o d/ctfeexpr.o d/dcast.o d/dclass.o \
+	d/declaration.o d/delegatize.o d/denum.o d/dimport.o d/dinterpret.o \
+	d/dmacro.o d/dmangle.o d/dmodule.o d/doc.o d/dscope.o d/dstruct.o \
+	d/dsymbol.o d/dtemplate.o d/dversion.o d/entity.o d/escape.o \
+	d/expression.o d/file.o d/filename.o d/func.o d/hdrgen.o \
+	d/identifier.o d/imphint.o d/init.o d/inline.o d/intrange.o d/json.o \
+	d/lexer.o d/mtype.o d/nogc.o d/newdelete.o d/nspace.o d/objc.o \
+	d/opover.o d/optimize.o d/outbuffer.o d/parse.o d/rmem.o \
+	d/rootobject.o d/sapply.o d/sideeffect.o d/speller.o d/statement.o \
+	d/statementsem.o d/staticassert.o d/stringtable.o d/tokens.o d/traits.o \
+	d/unittests.o d/utf.o d/utils.o
+
+# D Frontend generated files.
+D_GENERATED_SRCS = d/id.c d/id.h d/impcnvtab.c
+D_GENERATED_OBJS = d/id.o d/impcnvtab.o
+
+# Language-specific object files for D.
+D_OBJS = \
+	d/d-attribs.o d/d-builtins.o d/d-codegen.o d/d-convert.o \
+	d/d-diagnostic.o d/d-frontend.o d/d-incpath.o d/d-lang.o \
+	d/d-longdouble.o d/d-target.o d/decl.o d/expr.o d/imports.o \
+	d/intrinsics.o d/modules.o d/runtime.o d/toir.o d/typeinfo.o d/types.o
+
+# All language-specific object files for D.
+D_ALL_OBJS = $(D_FRONTEND_OBJS) $(D_GENERATED_OBJS) $(D_OBJS)
+
+d_OBJS = $(D_ALL_OBJS) d/d-spec.o
+
+cc1d$(exeext): $(D_ALL_OBJS) attribs.o $(BACKEND) $(LIBDEPS)
+	+$(LLINKER) $(ALL_LINKERFLAGS) $(LDFLAGS) -o $@ \
+		$(D_ALL_OBJS) attribs.o $(BACKEND) $(LIBS) $(BACKENDLIBS)
+
+# Documentation.
+
+D_TEXI_FILES = \
+	d/gdc.texi \
+	$(gcc_docdir)/include/fdl.texi \
+	$(gcc_docdir)/include/gpl_v3.texi \
+	$(gcc_docdir)/include/gcc-common.texi \
+	gcc-vers.texi
+
+doc/gdc.info: $(D_TEXI_FILES)
+	if test "x$(BUILD_INFO)" = xinfo; then \
+	  rm -f doc/gdc.info*; \
+	  $(MAKEINFO) $(MAKEINFOFLAGS) -I $(gcc_docdir) \
+		-I $(gcc_docdir)/include -o $@ $<; \
+	else true; fi
+
+doc/gdc.dvi: $(D_TEXI_FILES)
+	$(TEXI2DVI) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<
+
+doc/gdc.pdf: $(D_TEXI_FILES)
+	$(TEXI2PDF) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<
+
+$(build_htmldir)/d/index.html: $(D_TEXI_FILES)
+	$(mkinstalldirs) $(@D)
+	rm -f $(@D)/*
+	$(TEXI2HTML) -I $(gcc_docdir) -I $(gcc_docdir)/include \
+		-I $(srcdir)/d -o $(@D) $<
+
+.INTERMEDIATE: gdc.pod
+
+gdc.pod: d/gdc.texi
+	-$(TEXI2POD) -D gdc < $< > $@
+
+# Build hooks.
+
+d.all.cross: gdc-cross$(exeext)
+d.start.encap: gdc$(exeext)
+d.rest.encap:
+d.info: doc/gdc.info
+d.dvi: doc/gdc.dvi
+d.pdf: doc/gdc.pdf
+d.html: $(build_htmldir)/d/index.html
+d.srcinfo: doc/gdc.info
+	-cp -p $^ $(srcdir)/doc
+d.srcextra:
+
+d.tags: force
+	cd $(srcdir)/d; \
+	etags -o TAGS.sub *.c *.cc *.h dfrontend/*.h dfrontend/*.c; \
+	etags --include TAGS.sub --include ../TAGS.sub
+
+d.man: doc/gdc.1
+d.srcman: doc/gdc.1
+	-cp -p $^ $(srcdir)/doc
+
+# 'make check' in gcc/ looks for check-d, as do all toplevel D-related
+# check targets.  However, our DejaGNU framework requires 'check-gdc' as its
+# entry point.  We feed the former to the latter here.
+check-d: check-gdc
+lang_checks += check-gdc
+lang_checks_parallelized += check-gdc
+check_gdc_parallelize = 10
+
+# Install hooks.
+
+d.install-common: installdirs
+	-rm -f $(DESTDIR)$(bindir)/$(D_INSTALL_NAME)$(exeext)
+	$(INSTALL_PROGRAM) gdc$(exeext) $(DESTDIR)$(bindir)/$(D_INSTALL_NAME)$(exeext)
+	-if test -f cc1d$(exeext); then \
+	  if test -f gdc-cross$(exeext); then \
+	    :; \
+	  else \
+	    rm -f $(DESTDIR)$(bindir)/$(D_TARGET_INSTALL_NAME)$(exeext); \
+	    ( cd $(DESTDIR)$(bindir) && \
+	      $(LN) $(D_INSTALL_NAME)$(exeext) $(D_TARGET_INSTALL_NAME)$(exeext) ); \
+	  fi; \
+	fi
+
+d.install-plugin:
+
+d.install-info: $(DESTDIR)$(infodir)/gdc.info
+
+d.install-pdf: doc/gdc.pdf
+	@$(NORMAL_INSTALL)
+	test -z "$(pdfdir)" || $(mkinstalldirs) "$(DESTDIR)$(pdfdir)/gcc"
+	@for p in doc/gdc.pdf; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  f=$(pdf__strip_dir) \
+	  echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/gcc/$$f'"; \
+	  $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \
+	done
+
+d.install-html: $(build_htmldir)/d
+	@$(NORMAL_INSTALL)
+	test -z "$(htmldir)" || $(mkinstalldirs) "$(DESTDIR)$(htmldir)"
+	@for p in $(build_htmldir)/d; do \
+	  if test -f "$$p" || test -d "$$p"; then d=""; else d="$(srcdir)/"; fi; \
+	  f=$(html__strip_dir) \
+	  if test -d "$$d$$p"; then \
+	    echo " $(mkinstalldirs) '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(mkinstalldirs) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
+	    echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \
+	  else \
+	    echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \
+	  fi; \
+	done
+
+d.install-man: $(DESTDIR)$(man1dir)/$(D_INSTALL_NAME)$(man1ext)
+
+$(DESTDIR)$(man1dir)/$(D_INSTALL_NAME)$(man1ext): doc/gdc.1 installdirs
+	-rm -f $@
+	-$(INSTALL_DATA) $< $@
+	-chmod a-x $@
+
+d.uninstall:
+	-rm -rf $(DESTDIR)$(bindir)/$(D_INSTALL_NAME)$(exeext)
+	-rm -rf $(DESTDIR)$(man1dir)/$(D_INSTALL_NAME)$(man1ext)
+	-rm -rf $(DESTDIR)$(bindir)/$(D_TARGET_INSTALL_NAME)$(exeext)
+	-rm -rf $(DESTDIR)$(infodir)/gdc.info*
+
+# Clean hooks.
+
+d.mostlyclean:
+	-rm -f d/*$(objext)
+	-rm -f d/*$(coverageexts)
+	-rm -f $(D_GENERATED_SRCS) verstr.h
+	-rm -f d/gdc$(exeext) gdc-cross$(exeext) d/cc1d$(exeext)
+d.clean:
+d.distclean:
+d.maintainer-clean:
+	-rm -f $(docobjdir)/gdc.1
+
+# Stage hooks.
+
+d.stage1: stage1-start
+	-mv d/*$(objext) stage1/d
+d.stage2: stage2-start
+	-mv d/*$(objext) stage2/d
+d.stage3: stage3-start
+	-mv d/*$(objext) stage3/d
+d.stage4: stage4-start
+	-mv d/*$(objext) stage4/d
+d.stageprofile: stageprofile-start
+	-mv d/*$(objext) stageprofile/d
+d.stagefeedback: stagefeedback-start
+	-mv d/*$(objext) stagefeedback/d
+
+# Include the dfrontend and build directories for headers.
+D_INCLUDES = -I$(srcdir)/d -I$(srcdir)/d/dfrontend -Id
+
+CFLAGS-d/id.o += $(D_INCLUDES)
+CFLAGS-d/impcnvtab.o += $(D_INCLUDES)
+
+# Override build rules for D frontend.
+d/%.o: d/dfrontend/%.c $(D_GENERATED_SRCS) d/verstr.h
+	$(DMD_COMPILE) $(D_INCLUDES) $<
+	$(POSTCOMPILE)
+
+# Generated programs.
+d/idgen: d/idgen.dmdgen.o
+	+$(LINKER_FOR_BUILD) $(BUILD_LINKER_FLAGS) $(BUILD_LDFLAGS) -o $@ $^
+
+d/impcvgen: d/impcnvgen.dmdgen.o
+	+$(LINKER_FOR_BUILD) $(BUILD_LINKER_FLAGS) $(BUILD_LDFLAGS) -o $@ $^
+
+# Generated sources.
+d/id.c: d/idgen
+	cd d && ./idgen
+
+# idgen also generates id.h; just verify it exists.
+d/id.h: d/id.c
+
+d/impcnvtab.c: d/impcvgen
+	cd d && ./impcvgen
+
+d/verstr.h: d/VERSION
+	cat $^ > $@
+
+d/%.dmdgen.o: $(srcdir)/d/dfrontend/%.c
+	$(DMDGEN_COMPILE) $(D_INCLUDES) $<
+	$(POSTCOMPILE)
diff --git a/gcc/d/config-lang.in b/gcc/d/config-lang.in
new file mode 100644
index 00000000000..e3690850728
--- /dev/null
+++ b/gcc/d/config-lang.in
@@ -0,0 +1,33 @@ 
+# config-lang.in -- Top level configure fragment for gcc D frontend.
+# Copyright (C) 2006-2017 Free Software Foundation, Inc.
+
+# GCC is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+
+# GCC is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with GCC; see the file COPYING3.  If not see
+# <http://www.gnu.org/licenses/>.
+
+# Configure looks for the existence of this file to auto-config each language.
+# We define several parameters used by configure:
+#
+# language	- name of language as it would appear in $(LANGUAGES)
+# compilers	- value to add to $(COMPILERS)
+
+language="d"
+
+compilers="cc1d\$(exeext)"
+
+target_libs="target-libphobos target-zlib target-libbacktrace"
+
+gtfiles="\$(srcdir)/d/d-tree.h \$(srcdir)/d/d-builtins.cc \$(srcdir)/d/d-lang.cc \$(srcdir)/d/typeinfo.cc"
+
+# Do not build by default.
+build_by_default="no"
diff --git a/gcc/d/gdc.texi b/gcc/d/gdc.texi
new file mode 100644
index 00000000000..a05c7a872e0
--- /dev/null
+++ b/gcc/d/gdc.texi
@@ -0,0 +1,775 @@ 
+\input texinfo @c -*-texinfo-*-
+@setfilename gdc.info
+@settitle The GNU D Compiler
+
+@c Merge the standard indexes into a single one.
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
+@include gcc-common.texi
+
+@c Copyright years for this manual.
+@set copyrights-d 2011-2017
+
+@copying
+@c man begin COPYRIGHT
+Copyright @copyright{} @value{copyrights-d} Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, the Front-Cover Texts being (a) (see below), and
+with the Back-Cover Texts being (b) (see below).
+A copy of the license is included in the
+@c man end
+section entitled ``GNU Free Documentation License''.
+@ignore
+@c man begin COPYRIGHT
+man page gfdl(7).
+@c man end
+@end ignore
+
+@c man begin COPYRIGHT
+
+(a) The FSF's Front-Cover Text is:
+
+     A GNU Manual
+
+(b) The FSF's Back-Cover Text is:
+
+     You have freedom to copy and modify this GNU Manual, like GNU
+     software.  Copies published by the Free Software Foundation raise
+     funds for GNU development.
+@c man end
+@end copying
+
+@ifinfo
+@format
+@dircategory Software development
+@direntry
+* gdc: (gdc).               A GCC-based compiler for the D language
+@end direntry
+@end format
+
+@insertcopying
+@end ifinfo
+
+@titlepage
+@title The GNU D Compiler
+@versionsubtitle
+@author David Friedman, Iain Buclaw
+
+@page
+@vskip 0pt plus 1filll
+Published by the Free Software Foundation @*
+51 Franklin Street, Fifth Floor@*
+Boston, MA 02110-1301, USA@*
+@sp 1
+@insertcopying
+@end titlepage
+@contents
+@page
+
+@node Top
+@top Introduction
+
+This manual describes how to use @command{gdc}, the GNU compiler for
+the D programming language.  This manual is specifically about
+@command{gdc}.  For more information about the D programming
+language in general, including language specifications and standard
+package documentation, see @uref{http://dlang.org/}.
+
+@menu
+* Copying::                     The GNU General Public License.
+* GNU Free Documentation License::
+                                How you can share and copy this manual.
+* Invoking gdc::                How to run gdc.
+* Index::                       Index.
+@end menu
+
+
+@include gpl_v3.texi
+
+@include fdl.texi
+
+
+@node Invoking gdc
+@chapter Invoking gdc
+
+@c man title gdc A GCC-based compiler for the D language
+
+@ignore
+@c man begin SYNOPSIS gdc
+gdc [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}]
+    [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}]
+    [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
+    [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
+    [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
+
+Only the most useful options are listed here; see below for the
+remainder.
+@c man end
+@c man begin SEEALSO
+gpl(7), gfdl(7), fsf-funding(7), gcc(1)
+and the Info entries for @file{gdc} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gdc
+
+The @command{gdc} command is a frontend to @command{gcc} and supports many
+of the same options.  @xref{Option Summary, , Option Summary, gcc,
+Using the GNU Compiler Collection (GCC)}.  This manual only documents
+the options specific to @command{gdc}.
+
+@c man end
+
+@menu
+* Input and Output files::  Controlling the kind of output:
+                            an executable, object files, assembler files,
+* Runtime Options::         Options controlling runtime behaviour
+* Directory Options::       Where to find module files
+* Code Generation::         Options controlling the output of gdc
+* Warnings::                Options controlling warnings specific to gdc
+* Linking::                 Options influceing the linking step
+* Developer Options::       Options you won't use
+* Environment Variables::   Environment variables that affect @command{gdc}.
+@end menu
+
+@c man begin OPTIONS
+
+@node Input and Output files
+@section Input and Output files
+@cindex suffixes for D source
+@cindex D source file suffixes
+
+For any given input file, the file name suffix determines what kind of
+compilation is done.  The following kinds of input file names are supported:
+
+@table @gcctabopt
+@item @var{file}.d
+D source files.
+@item @var{file}.dd
+Ddoc source files.
+@item @var{file}.di
+D interface files.
+@end table
+
+You can specify more than one input file on the @command{gdc} command line,
+in which case they will all be compiled.  If you specify a
+@code{-o @var{file}} option, all the input files will be compiled together,
+producing a single output file, named @var{file}.  This is allowed even
+when using @code{-S} or @code{-c}.
+
+@cindex D interface files.
+A D interface file contains only what an import of the module needs,
+rather than the whole implementation of that module.  They can be created
+by @command{gdc} from a D source file by using the @code{-fintfc} option.
+When the compiler resolves an import declaration, it searches for matching
+@file{.di} files first, then for @file{.d}.
+
+@cindex Ddoc source files.
+A Ddoc source file contains code in the D macro processor language.  It is
+primarily designed for use in producing user documentation from embedded
+comments, with a slight affinity towards HTML generation.  If a @file{.d}
+source file starts with the string @code{Ddoc} then it is treated as general
+purpose documentation, not as a D source file.
+
+@node Runtime Options
+@section Runtime Options
+@cindex options, runtime
+
+These options affect the runtime behavior of programs compiled with
+@command{gdc}.
+
+@table @gcctabopt
+
+@item -fall-instantiations
+@cindex @option{-fall-instantiations}
+@cindex @option{-fno-all-instantiations}
+Generate code for all template instantiations.  The default template emission
+strategy is to not generate code for declarations that were either
+instantiated speculatively, such as from @code{__traits(compiles, ...)}, or
+that come from an imported module not being compiled.
+
+@item -fno-assert
+@cindex @option{-fassert}
+@cindex @option{-fno-assert}
+Turn off code generation for @code{assert} contracts.
+
+@item -fno-bounds-check
+@cindex @option{-fbounds-check}
+@cindex @option{-fno-bounds-check}
+Turns off array bounds checking for all functions, which can improve
+performance for code that uses array extensively.  Note that this
+can result in unpredictable behavior if the code in question actually
+does violate array bounds constraints.  It is safe to use this option
+if you are sure that your code will never throw a @code{RangeError}.
+
+@item -fbounds-check=@var{value}
+@cindex @option{-fbounds-check=}
+An alternative to @option{-fbounds-check} that allows more control
+as to where bounds checking is turned on or off.  The following values
+are supported:
+
+@table @samp
+@item on
+@cindex @option{-fbounds-check=on}
+Turns on array bounds checking for all functions.
+@item safeonly
+@cindex @option{-fbounds-check=safeonly}
+Turns on array bounds checking only for @code{@@safe} functions.
+@item off
+@cindex @option{-fbounds-check=off}
+Turns off array bounds checking completely.
+@end table
+
+@item -fno-builtin
+@cindex @option{-fbuiltin}
+@cindex @option{-fno-builtin}
+Don't recognize built-in functions that do not begin with
+@samp{__builtin_} as prefix.  By default, the compiler will recognize
+when a function in the @code{core.stdc} package is a built-in function.
+
+@item -fdebug
+@item -fdebug=@var{value}
+@cindex @option{-fdebug}
+@cindex @option{-fno-debug}
+Turn on compilation of conditional @code{debug} code into the program.
+The @option{-fdebug} option itself sets the debug level to @code{1},
+while @option{-fdebug=} enables @code{debug} code that are identified
+by any of the following values:
+
+@table @samp
+@item level
+@cindex @option{-fdebug=level}
+Sets the debug level to @var{level}, any @code{debug} code <= @var{level}
+is compiled into the program.
+@item ident
+@cindex @option{-fdebug=ident}
+Turns on compilation of any @code{debug} code identified by @var{ident}.
+@end table
+
+@item -fno-invariants
+@cindex @option{-finvariants}
+@cindex @option{-fno-invariants}
+Turns off code generation for class @code{invariant} contracts.
+
+@item -fno-moduleinfo
+@cindex @option{-fmoduleinfo}
+@cindex @option{-fno-moduleinfo}
+Turns off generation of the @code{ModuleInfo} and related functions
+that would become unreferenced without it, which may allow linking
+to programs not written in D.  Functions that will not be generated
+include module constructor and destructors (@code{static this} and
+@code{static ~this}), @code{unittest} code, and @code{DSO} registry
+functions for dynamically linked code.
+
+@item -fonly=@var{filename}
+@cindex @option{-fonly}
+Tells the compiler to parse and run semantic analysis on all modules
+on the command line, but only generate code for the module specified
+by @var{filename}.
+
+@item -fno-postconditions
+@cindex @option{-fpostconditions}
+@cindex @option{-fno-postconditions}
+Turns off code generation for postcondition @code{out} contracts.
+
+@item -fno-preconditions
+@cindex @option{-fpreconditions}
+@cindex @option{-fno-preconditions}
+Turns off code generation for precondition @code{in} contracts.
+
+@item -frelease
+@cindex @option{-frelease}
+@cindex @option{-fno-release}
+Turns on compiling in release mode, which means not emitting runtime
+checks for contracts and asserts.  Array bounds checking is not done
+for @code{@@system} and @code{@@trusted} functions, and assertion
+failures are undefined behaviour.
+
+This is equivalent to compiling with the following options:
+
+@example
+gdc -fno-assert -fbounds-check=safe -fno-invariants \
+    -fno-postconditions -fno-preconditions -fno-switch-errors
+@end example
+
+@item -fno-switch-errors
+@cindex @option{-fswitch-errors}
+@cindex @option{-fno-switch-errors}
+This option controls what code should be generated when no case is
+matched in a @code{final switch} statement.  The default run time
+behavior is that a @code{SwitchError} will be thrown.  Turning off
+@option{-fswitch-errors} means that instead the execution of the
+program is immediately halted.
+
+@item -funittest
+@cindex @option{-funittest}
+@cindex @option{-fno-unittest}
+Turns on compilation of @code{unittest} code, and turns on the
+@code{version(unittest)} identifier.  This implies @option{-fassert}.
+
+@item -fversion=@var{value}
+@cindex @option{-fversion}
+Turns on compilation of conditional @code{version} code into the program
+identified by any of the following values:
+
+@table @samp
+@item level
+@cindex @option{-fversion=level}
+Sets the version level to @var{level}, any @code{version} code >= @var{level}
+is compiled into the program.
+@item ident
+@cindex @option{-fversion=ident}
+Turns on compilation of @code{version} code identified by @var{ident}.
+@end table
+
+@end table
+
+@node Directory Options
+@section Options for Directory Search
+@cindex directory options
+@cindex options, directory search
+@cindex search path
+
+These options specify directories to search for files, libraries, and
+other parts of the compiler:
+
+@table @gcctabopt
+
+@item -I@var{dir}
+@cindex @option{-I}
+Specify a directory to use when searching for imported modules at
+compile time.  Multiple @option{-I} options can be used, and the
+paths are searched in the same order.
+
+@item -J@var{dir}
+@cindex @option{-J}
+Specify a directory to use when searching for files in string imports
+at compile time.  This switch is required in order to use
+@code{import(file)} expressions.  Multiple @option{-J} options can be
+used, and the paths are searched in the same order.
+
+@item -L@var{dir}
+@cindex @option{-L}
+When linking, specify a library search directory, as with @command{gcc}.
+
+@item -B@var{dir}
+@cindex @option{-B}
+This option specifies where to find the executables, libraries,
+source files, and data files of the compiler itself, as with @command{gcc}.
+
+@item -fmodule-filepath=@var{module}=@var{spec}
+@cindex @option{-fmodule-filepath}
+This option manipulates file paths of imported modules, such that if an
+imported module matches all or the leftmost part of @var{module}, the file
+path in @var{spec} is used as the location to search for D sources.
+This is used when the source file path and names are not the same as the
+package and module hierachy.  Consider the following examples:
+
+@example
+gdc test.d -fmodule-filepath=A.B=foo.d -fmodule-filepath=C=bar
+@end example
+
+This will tell the compiler to search in all import paths for the source
+file @var{foo.d} when importing @var{A.B}, and the directory @var{bar/}
+when importing @var{C}, as annotated in the following D code:
+
+@example
+module test;
+import A.B;     // Matches A.B, searches for foo.d
+import C.D.E;   // Matches C, searches for bar/D/E.d
+import A.B.C;   // No match, searches for A/B/C.d
+@end example
+
+@item -imultilib @var{dir}
+@cindex @option{-imultilib}
+Use @var{dir} as a subdirectory of the gcc directory containing
+target-specific D sources and interfaces.
+
+@item -iprefix @var{prefix}
+@cindex @option{-iprefix}
+Specify @var{prefix} as the prefix for the gcc directory containing
+target-specific D sources and interfaces.  If the @var{prefix} represents
+a directory, you should include the final @code{'/'}.
+
+@item -nostdinc
+@cindex @option{-nostdinc}
+Do not search the standard system directories for D source and interface
+files.  Only the directories that have been specified with @option{-I} options
+(and the directory of the current file, if appropriate) are searched.
+
+@end table
+
+@node Code Generation
+@section Code Generation
+@cindex options, code generation
+
+In addition to the many @command{gcc} options controlling code generation,
+@command{gdc} has several options specific to itself.
+
+@table @gcctabopt
+
+@item -M
+@cindex @option{-M}
+Output the module dependencies of all source files being compiled in a
+format suitable for @command{make}.  The compiler outputs one
+@command{make} rule containing the object file name for that source file,
+a colon, and the names of all imported files.
+
+@item -MM
+@cindex @option{-MM}
+Like @option{-M} but does not mention imported modules from the D standard
+library package directories.
+
+@item -MF @var{file}
+@cindex @option{-MF}
+When used with @option{-M} or @option{-MM}, specifies a @var{file} to write
+the dependencies to.  When used with the driver options @option{-MD} or
+@option{-MMD}, @option{-MF} overrides the default dependency output file.
+
+@item -MG
+@cindex @option{-MG}
+This option is for compatibility with @command{gcc}, and is ignored by the
+compiler.
+
+@item -MP
+@cindex @option{-MP}
+Outputs a phony target for each dependency other than the modules being
+compiled, causing each to depend on nothing.
+
+@item -MT @var{target}
+@cindex @option{-MT}
+Change the @var{target} of the rule emitted by dependency generation
+to be exactly the string you specify.  If you want multiple targets,
+you can specify them as a single argument to @option{-MT}, or use
+multiple @option{-MT} options.
+
+@item -MQ @var{target}
+@cindex @option{-MQ}
+Same as @option{-MT}, but it quotes any characters which are special to
+@command{make}.
+
+@item -MD
+@cindex @option{-MD}
+This option is equivalent to @option{-M -MF @var{file}}.  The driver
+determines @var{file} based on the name of the input file, removes any
+directory components and suffix, and applies a @file{.deps} suffix.
+
+@item -MMD
+@cindex @option{-MMD}
+Like @option{-MD} but does not mention imported modules from the D standard
+library package directories.
+
+@item -X
+@cindex @option{-X}
+Output information describing the contents of all source files being
+compiled in JSON format to a file.  The driver determines @var{file} based
+on the name of the input file, removes any directory components and suffix,
+and applies a @file{.json} suffix.
+
+@item -Xf @var{file}
+@cindex @option{-Xf}
+Same as @option{-X}, but writes all JSON contents to the specified
+@var{file}.
+
+@item -fdeps
+@cindex @option{-fdeps}
+Dump module dependencies of all source files being compiled in a machine
+readable format.  Suitable for any build tool that needs to track source
+file dependencies for incremental builds.
+
+@item -fdeps=@var{file}
+@cindex @option{-fdeps=}
+Same as @option{-fdeps}, but writes dependencies to the specified
+@var{file}.
+
+@item -fdoc
+@cindex @option{-fdoc}
+Generates @code{Ddoc} documentation and writes to a file.  The compiler
+determines @var{file} based on the name of the input file, removes any
+directory components and suffix, and applies a @file{.html} suffix.
+
+@item -fdoc-dir=@var{dir}
+@cindex @option{-fdoc-dir}
+Same as @option{-fdoc}, but writes documentation to @var{dir} directory.
+This option can be used with @option{-fdoc-file=@var{file}} to
+independently set the output file and directory path.
+
+@item -fdoc-file=@var{file}
+@cindex @option{-fdoc-file}
+Same as @option{-fdoc}, but writes documentation to @var{file}.  This
+option can be used with @option{-fdoc-dir=@var{dir}} to independently
+set the output file and directory path.
+
+@item -fdoc-inc=@var{file}
+@cindex @option{-fdoc-inc}
+Specify @var{file} as a @var{Ddoc} macro file to be read.  Multiple
+@option{-fdoc-inc} options can be used, and files are read and processed
+in the same order.
+
+@item -fintfc
+@cindex @option{-fintfc}
+Generates D interface files for all modules being compiled.  The compiler
+determines the output @var{file} based on the name of the input file,
+removes any directory components and suffix, and applies the @file{.di}
+suffix.
+
+@item -fintfc-dir=@var{dir}
+@cindex @option{-fintfc-dir}
+Same as @option{-fintfc}, but writes interface files to @var{dir}
+directory.  This option can be used with @option{-fintfc-file=@var{file}}
+to independently set the output file and directory path.
+
+@item -fintfc-file=@var{filename}
+@cindex @option{-fintfc-file}
+Same as @option{-fintfc} but writes interface files to @var{file}.  This
+option can be used with @option{-fintfc-dir=@var{dir}} to independently
+set the output file and directory path.
+
+@end table
+
+@node Warnings
+@section Warnings
+@cindex options to control warnings
+@cindex warning messages
+@cindex messages, warning
+@cindex suppressing warnings
+
+Warnings are diagnostic messages that report constructions that
+are not inherently erroneous but that are risky or suggest there
+is likely to be a bug in the program.  Unless @option{-Werror} is
+specified, they do not prevent compilation of the program.
+
+@table @gcctabopt
+
+@item -Wall
+@cindex @option{-Wall}
+@cindex @option{-Wno-all}
+Turns on all warnings messages.  Warnings are not a defined part of
+the D language, and all constructs for which this may generate a
+warning message are legal code.
+
+@item -Wcast-result
+@cindex @option{-Wcast-result}
+@cindex @option{-Wno-cast-result}
+Warn about casts that will produce a null or zero result.  Currently
+this is only done for casting between an imaginary and non-imaginary
+data type, or casting between a D and C++ class.
+
+@item -Wno-deprecated
+@cindex @option{-Wdeprecated}
+@cindex @option{-Wno-deprecated}
+Do not warn about usage of deprecated features and symbols with
+@code{deprecated} attributes.
+
+@item -Werror
+@cindex @option{-Werror}
+@cindex @option{-Wno-error}
+Turns all warnings into errors.
+
+@item -Wspeculative
+@cindex @option{-Wspeculative}
+@cindex @option{-Wno-speculative}
+Report on all error messages from speculative compiles, such as
+@code{__traits(compiles, ...)}.  This option does not report
+messages as warnings, and these messages therefore never become
+errors when the @option{-Werror} option is also used.
+
+@item -Wtemplates
+@cindex @option{-Wtemplates}
+@cindex @option{-Wno-templates}
+Warn when a template instantiation is encountered.  Some coding
+rules disallow templates, and this may be used to enforce that rule.
+
+@item -Wunknown-pragmas
+@cindex @option{-Wunknown-pragmas}
+@cindex @option{-Wno-unknown-pragmas}
+Warn when a @code{pragma()} is encountered that is not understood by
+@command{gdc}.  This differs from @option{-fignore-unknown-pragmas}
+where a pragma that is part of the D language, but not implemented by
+the compiler, will not get reported.
+
+@item -fignore-unknown-pragmas
+@cindex @option{-fignore-unknown-pragmas}
+@cindex @option{-fno-ignore-unknown-pragmas}
+Turns off errors for unsupported pragmas.
+
+@item -fmax-errors=@var{n}
+@cindex @option{-fmax-errors}
+Limits the maximum number of error messages to @var{n}, at which point
+@command{gdc} bails out rather than attempting to continue processing the
+source code.  If @var{n} is 0 (the default), there is no limit on the
+number of error messages produced.
+
+@item -fproperty
+@cindex @option{-fproperty}
+@cindex @option{-fno-property}
+Enforces the @code{@@property} syntax in D.
+
+@item -fsyntax-only
+@cindex @option{-fsyntax-only}
+@cindex @option{-fno-syntax-only}
+Check the code for syntax errors, but do not actually compile it.  This
+only suppresses the generation of the object code, and can be used in
+conjunction with @option{-fdoc} or @option{-fintfc} options.
+
+@item -ftransition=@var{id}
+@cindex @option{-ftransition}
+Report additional information about D language changes identified by
+@var{id}.  The following values are supported:
+
+@table @samp
+@item all
+@cindex @option{-ftransition=all}
+List information on all language changes.
+@item checkimports
+@cindex @option{-ftransition=checkimports}
+Give deprecation messages about @option{-ftransition=import} anomalies.
+@item complex
+@cindex @option{-ftransition=complex}
+List all usages of complex or imaginary types.
+@item dip1000
+@cindex @option{-ftransition=dip1000}
+Implements @uref{http://wiki.dlang.org/DIP1000} (experimental).
+@item dip25
+@cindex @option{-ftransition=dip25}
+Implements @uref{http://wiki.dlang.org/DIP25} (experimental).
+@item field
+@cindex @option{-ftransition=field}
+List all non-mutable fields which occupy an object instance.
+@item import
+@cindex @option{-ftransition=import}
+Tells the compiler to revert to using an old lookup behavior for resolving
+unqualified symbol names, where this was done in a single pass, ignoring any
+protection attributes.  The default name lookup strategy is to use two passes,
+the first ignoring imported declarations, and the second only looking at imports.
+The protection (@code{private}, @code{package}, @code{protected}) of symbols is
+also enforced to resolve any conflicts between private and public symbols.
+@item nogc
+@cindex @option{-ftransition=nogc}
+List all hidden GC allocations.
+@item tls
+@cindex @option{-ftransition=tls}
+List all variables going into thread local storage.
+@end table
+
+@end table
+
+@node Linking
+@section Options for Linking
+@cindex options, linking
+@cindex linking, static
+
+These options come into play when the compiler links object files into an
+executable output file. They are meaningless if the compiler is not doing
+a link step.
+
+@table @gcctabopt
+
+@item -defaultlib @var{libname}
+@cindex @option{-defaultlib}
+Specify the library to use instead of libphobos when linking.  Options
+specifying the linkage of libphobos, such as @option{-static-libphobos}
+or @option{-shared-libphobos}, are ignored.
+
+@item -debuglib
+@cindex @option{-debuglib}
+Specify the debug library to use instead of libphobos when linking.
+This option has no effect unless the @option{-g} option was also given
+on the command line.  Options specifying the linkage of libphobos, such
+as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored.
+
+@item -nophoboslib
+@cindex @option{-nophoboslib}
+Do not use the Phobos or D runtime library when linking.  Options specifying
+the linkage of libphobos, such as @option{-static-libphobos} or
+@option{-shared-libphobos}, are ignored.  The standard system libraries are
+used normally, unless @option{-nostdlib} or @option{-nodefaultlibs} is used.
+
+@item -shared-libphobos
+@cindex @option{-shared-libphobos}
+On systems that provide @file{libgphobos} and @file{libgdruntime} as a
+shared and a static library, this option forces the use of the shared
+version. If no shared version was built when the compiler was configured,
+this option has no effect.
+
+@item -static-libphobos
+@cindex @option{-static-libphobos}
+On systems that provide @file{libgphobos} and @file{libgdruntime} as a
+shared and a static library, this option forces the use of the static
+version. If no static version was built when the compiler was configured,
+this option has no effect.
+
+@end table
+
+@node Developer Options
+@section Developer Options
+@cindex developer options
+@cindex debug dump options
+@cindex dump options
+
+This section describes command-line options that are primarily of
+interest to developers or language tooling.
+
+@table @gcctabopt
+
+@item -fdump-d-original
+@cindex @option{-fdump-d-original}
+Dump the front-end AST after after parsing and running semantic on
+the source program.  Only really useful for debugging the compiler
+itself.
+
+@item -v
+@cindex @option{-v}
+Dump information about the compiler language processing stages as the source
+program is being compiled.  This includes listing all modules that are
+processed through the @code{parse}, @code{semantic}, @code{semantic2}, and
+@code{semantic3} stages; all @code{import} modules and their file paths;
+and all @code{function} bodies that are being compiled.
+
+@end table
+
+@c man end
+
+@node Environment Variables
+@section Environment variables affecting @command{gdc}
+@cindex environment variable
+
+@c man begin ENVIRONMENT
+
+In addition to the many @command{gcc} environment variables that control
+its operation, @command{gdc} has a few environment variables specific to
+itself.
+
+@vtable @env
+
+@item D_IMPORT_PATH
+@findex D_IMPORT_PATH
+The value of @env{D_IMPORT_PATH} is a list of directories separated by a
+special character, much like @env{PATH}, in which to look for imports.
+The special character, @code{PATH_SEPARATOR}, is target-dependent and
+determined at GCC build time.  For Microsoft Windows-based targets it is a
+semicolon, and for almost all other targets it is a colon.
+
+@item DDOCFILE
+@findex DDOCFILE
+If @env{DDOCFILE} is set, it specifies a text file of macro definitions
+to be read and used by the Ddoc generator.  This overrides any macros
+defined in other @file{.ddoc} files.
+
+@end vtable
+
+@c man end
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye