Re: [PATCH 04/14] Add D front-end (GDC) config, Makefile, and manpages.

[Iain Buclaw <ibuclaw at gdcproject dot org>]

On Tue, 16 Oct 2018 at 11:31, Richard Sandiford
<richard.sandiford@arm.com> wrote:
>
> I'll pretend to be a doc reviewer...
>
> Iain Buclaw <ibuclaw@gdcproject.org> writes:
> > +@page
> > +@vskip 0pt plus 1filll
> > +Published by the Free Software Foundation @*
> > +51 Franklin Street, Fifth Floor@*
> > +Boston, MA 02110-1301, USA@*
>
> Would be good to copy the expanded GNU Press stuff from gcc.texi.
>
> > +The @command{gdc} command is a frontend to @command{gcc} and supports many
> > +of the same options.
>
> A bit pedantic, but I think this should be something like:
>
>   The @command{gdc} command is the GNU compiler for the D language and
>   supports many of the same options as @command{gcc}.
>
> > +@menu
> > +* Input and Output files::  Controlling the kind of output:
> > +                            an executable, object files, assembler files,
> > +* Runtime Options::         Options controlling runtime behaviour
>
> "behavior"
>
> > +* 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
>
> "influencing"
>
> > +* Developer Options::       Options you won't use
>
> Don't know if this came from an earlier version of the main GCC manual,
> but it seems a bit off-message for the FSF.  Something boring like:
>
>   Options useful for developers of gdc
>
> might be better.
>
> > +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
>
> The documentation convention is to avoid the future tense for things
> like this.  s/will all be/are all/ doesn't read very naturally so it
> might need to be reworded.
>
> > +@code{-o @var{file}} option, all the input files will be compiled together,
>
> Same here.
>
> > +@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
>
> "uses arrays extensively"?  Or maybe some markup is missing from "array".
>
> > +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}.
>
> s/will never throw/never throws/
>
> > +@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.
>
> maybe "unless they begin with the prefix @samp{__builtin_}"?
> s/will recognize/recognizes/
>
> > +@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
>
> Should be @var rather than @samp in the @table.  Also @var{...} in
> the @option{...}s.
>
> > +@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
>
> s/will not be/are not/
>
> > +include module constructor and destructors (@code{static this} and
>
> s/constructor/constructors/?  Or is there only one of each, in which
> case maybe "the module constructor and destructor".
>
> > +@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.
>
> "behavior"
>
> > +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
>
> s/should be/is/
>
> > +matched in a @code{final switch} statement.  The default run time
> > +behavior is that a @code{SwitchError} will be thrown.  Turning off
>
> "is to throw a @code{SwitchError}"
>
> > +@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
>
> Same comments as above about @var{}.
>
> > +
> > +@item -fno-weak
> > +@cindex @option{-fweak}
> > +@cindex @option{-fno-weak}
> > +Turns off emission of instantiated declarations that can be defined in multiple
> > +objects as weak or one-only symbols.  The default is to emit all public symbols
> > +as weak, unless there lacks target support.  Disabling this options means that
> > +common symbols are instead put in COMDAT or become private.
>
> Maybe "unless the target lacks support for weak symbols"?
>
> > +@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.
>
> Should this be @var{file}?
>
> > +@item -fmodule-file=@var{module}=@var{spec}
> > +@cindex @option{-fmodule-file}
> > +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:
>
> "hierarchy"
>
> > +@item -imultilib @var{dir}
> > +@cindex @option{-imultilib}
> > +Use @var{dir} as a subdirectory of the gcc directory containing
> > +target-specific D sources and interfaces.
>
> Which gcc directory does this mean?
>
> > +@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{'/'}.
>
> Same here.  What does a prefix without the "/" mean here?  It doesn't
> seem from the docs that it acts with a -iwithprefix option.
>
> > +@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.
>
> When's that appropriate for D?
>
> > +@item -H
> > +@cindex @option{-H}
> > +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.
>
> Marking up @var{file} looks odd here, since nothing else refers to it.
>
> > +@item -Hd @var{dir}
> > +@cindex @option{-Hd}
> > +Same as @option{-H}, but writes interface files to @var{dir} directory.
>
> "directory @var{dir}"?
>
> > +@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.
>
> This sounded at first like the driver removes the components after
> determining @var{file}, whereas I'm guessing that's how it determines
> @var{file}.  Maybe something like:
>
>   determines @var{file} by removing any directory components and suffix
>   from the input file and then adding a @file{.deps} suffix.
>
> if so?
>
> > +@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.
>
> Same sort of thing here.
>
> > +@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.
>
> Here too.  "writes it"?
>
> > +@item -fdoc-dir=@var{dir}
> > +@cindex @option{-fdoc-dir}
> > +Same as @option{-fdoc}, but writes documentation to @var{dir} directory.
>
> "directory @var{dir}"?
>
> > +@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.
>
> "valid code".  But I assume this is "all" in the same way that it's
> "all" for C and C++?  Might be better to use something like the
> invoke.texi entry, which says:
>
>     This enables all the warnings about constructions that some users
>     consider questionable, and that are easy to avoid (or modify to
>     prevent the warning), even in conjunction with macros.
>
> > +@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.
>
> "Report on all error messages" sounds a bit odd.
>
> > +@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.
>
> Future tense.
>
> > +@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{-H} options.
>
> "object code" might be confusing since I assume we wouldn't generate
> assembly code either.
>
> > +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.
>
> Two spaces before "They".
>
> > +@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.
>
> "after running semantic" sounds odd.  Based on -v, maybe "after the
> @code{semantic} stage", if that's what it means?
>
> Looks OK otherwise.
>

Posting diff since last patch following above review.

Regards
--
Iain

---

Attachment: 04-v4v5-d-frontend-misc.patch.xz
Description: Binary data