On Tue, 16 Oct 2018 at 11:31, Richard Sandiford <richard.sandif...@arm.com> wrote: > > I'll pretend to be a doc reviewer... > > Iain Buclaw <ibuc...@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 ---
04-v4v5-d-frontend-misc.patch.xz
Description: Binary data