diff --git a/src/dmd/cli.d b/src/dmd/cli.d index 7cb4da968d20..b08ab26457fb 100644 --- a/src/dmd/cli.d +++ b/src/dmd/cli.d @@ -7,7 +7,7 @@ * However, this file will be used to generate the * $(LINK2 https://dlang.org/dmd-linux.html, online documentation) and MAN pages. * - * Copyright: Copyright (c) 1999-2018 by The D Language Foundation, All Rights Reserved + * Copyright: Copyright (C) 1999-2018 by The D Language Foundation, All Rights Reserved * Authors: $(LINK2 http://www.digitalmars.com, Walter Bright) * License: $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost License 1.0) * Source: $(LINK2 https://github.com/dlang/dmd/blob/master/src/dmd/cli.d, _cli.d) @@ -73,18 +73,50 @@ bool isCurrentTargetOS(TargetOS os) } /** -Contains all available CLI $(LREF Option)s. +Contains all available CLI $(LREF Usage.Option)s. -See_Also: $(LREF Option) +See_Also: $(LREF Usage.Option) */ struct Usage { - /// Representation of a CLI `Option` + /** + * Representation of a CLI `Option` + * + * The DDoc description `ddoxText` is only available when compiled with `-version=DdocOptions`. + */ struct Option { string flag; /// The CLI flag without leading `-`, e.g. `color` string helpText; /// A detailed description of the flag TargetOS os = TargetOS.all; /// For which `TargetOS` the flags are applicable + + // Needs to be version-ed to prevent the text ending up in the binary + // See also: https://issues.dlang.org/show_bug.cgi?id=18238 + version(DdocOptions) string ddocText; /// Detailed description of the flag (in Ddoc) + + /** + * Params: + * flag = CLI flag without leading `-`, e.g. `color` + * helpText = detailed description of the flag + * os = for which `TargetOS` the flags are applicable + * ddocText = detailed description of the flag (in Ddoc) + */ + this(string flag, string helpText, TargetOS os = TargetOS.all) + { + this.flag = flag; + this.helpText = helpText; + version(DdocOptions) this.ddocText = helpText; + this.os = os; + } + + /// ditto + this(string flag, string helpText, string ddocText, TargetOS os = TargetOS.all) + { + this.flag = flag; + this.helpText = helpText; + version(DdocOptions) this.ddocText = ddocText; + this.os = os; + } } /// Returns all available CLI options @@ -93,19 +125,60 @@ struct Usage "generate code for all template instantiations" ), Option("betterC", - "omit generating some runtime information and helper functions" + "omit generating some runtime information and helper functions", + "Adjusts the compiler to implement D as a $(LINK2 $(ROOT_DIR)spec/betterc.html, better C): + $(UL + $(LI Predefines `D_BetterC` $(LINK2 $(ROOT_DIR)spec/version.html#predefined-versions, version).) + $(LI $(LINK2 $(ROOT_DIR)spec/expression.html#AssertExpression, Assert Expressions), when they fail, + call the C runtime library assert failure function + rather than a function in the D runtime.) + $(LI $(LINK2 $(ROOT_DIR)spec/arrays.html#bounds, Array overflows) + call the C runtime library assert failure function + rather than a function in the D runtime.) + $(LI $(LINK2 spec/statement.html#final-switch-statement/, Final switch errors) + call the C runtime library assert failure function + rather than a function in the D runtime.) + $(LI Does not automatically link with phobos runtime library.) + $(UNIX + $(LI Does not generate Dwarf `eh_frame` with full unwinding information, i.e. exception tables + are not inserted into `eh_frame`.) + ) + $(LI Module constructors and destructors are not generated meaning that + $(LINK2 $(ROOT_DIR)spec/class.html#StaticConstructor, static) and + $(LINK2 $(ROOT_DIR)spec/class.html#SharedStaticConstructor, shared static constructors) and + $(LINK2 $(ROOT_DIR)spec/class.html#StaticDestructor, destructors) + will not get called.) + $(LI `ModuleInfo` is not generated.) + $(LI $(LINK2 $(ROOT_DIR)phobos/object.html#.TypeInfo, `TypeInfo`) + instances will not be generated for structs.) + )", ), Option("boundscheck=[on|safeonly|off]", - "bounds checks on, in @safe only, or off" + "bounds checks on, in @safe only, or off", + `Controls if bounds checking is enabled. + $(UL + $(LI $(I on): Bounds checks are enabled for all code. This is the default.) + $(LI $(I safeonly): Bounds checks are enabled only in $(D @safe) code. + This is the default for $(SWLINK -release) builds.) + $(LI $(I off): Bounds checks are disabled completely (even in $(D @safe) + code). This option should be used with caution and as a + last resort to improve performance. Confirm turning off + $(D @safe) bounds checks is worthwhile by benchmarking.) + )` ), Option("c", - "do not link" + "compile only, do not link" ), Option("color", "turn colored console output on" ), Option("color=[on|off]", - "force colored console output on or off" + "force colored console output on or off", + `Show colored console output. The default depends on terminal capabilities. + $(UL + $(LI $(B on): always use colored output. Same as $(B -color)) + $(LI $(B off): never use colored output.) + )` ), Option("conf=", "use config file at filename" @@ -114,19 +187,33 @@ struct Usage "do code coverage analysis" ), Option("cov=", - "require at least nnn% code coverage" + "require at least nnn% code coverage", + `Perform $(LINK2 $(ROOT_DIR)code_coverage.html, code coverage analysis) and generate + $(TT .lst) file with report.) +--- +dmd -cov -unittest myprog.d +--- + `, ), Option("D", - "generate documentation" + "generate documentation", + `$(P Generate $(LINK2 $(ROOT_DIR)spec/ddoc.html, documentation) from source.) + $(P Note: mind the $(LINK2 $(ROOT_DIR)spec/ddoc.html#security, security considerations).) + `, ), Option("Dd", - "write documentation file to directory" + "write documentation file to directory", + `Write documentation file to $(I directory) . $(SWLINK -op) + can be used if the original package hierarchy should + be retained`, ), Option("Df", "write documentation file to filename" ), Option("d", - "silently allow deprecated features" + "silently allow deprecated features", + `Silently allow $(DDLINK deprecate,deprecate,deprecated features) and use of symbols with + $(DDSUBLINK $(ROOT_DIR)spec/attribute, deprecated, deprecated attributes).`, ), Option("dw", "show use of deprecated features as warnings (default)" @@ -135,29 +222,38 @@ struct Usage "show use of deprecated features as errors (halt compilation)" ), Option("debug", - "compile in debug code" + "compile in debug code", + `Compile in $(LINK2 spec/version.html#debug, debug) code`, ), Option("debug=", - "compile in debug code <= level" + "compile in debug code <= level", + `Compile in $(LINK2 spec/version.html#debug, debug level) <= $(I level)`, ), Option("debug=", - "compile in debug code identified by ident" + "compile in debug code identified by ident", + `Compile in $(LINK2 spec/version.html#debug, debug identifier) $(I ident)`, ), Option("debuglib=", - "set symbolic debug library to name" + "set symbolic debug library to name", + `Link in $(I libname) as the default library when + compiling for symbolic debugging instead of $(B $(LIB)). + If $(I libname) is not supplied, then no default library is linked in.` ), Option("defaultlib=", - "set default library to name" + "set default library to name", + `Link in $(I libname) as the default library when + not compiling for symbolic debugging instead of $(B $(LIB)). + If $(I libname) is not supplied, then no default library is linked in.`, ), Option("deps", "print module dependencies (imports/file/version/debug/lib)" ), Option("deps=", - "write module dependencies to filename (only imports)" - ), - Option("fPIC", - "generate position independent code", - TargetOS.linux + "write module dependencies to filename (only imports)", + `Without $(I filename), print module dependencies + (imports/file/version/debug/lib). + With $(I filename), write module dependencies as text to $(I filename) + (only imports).`, ), Option("dip25", "implement http://wiki.dlang.org/DIP25" @@ -168,8 +264,23 @@ struct Usage Option("dip1008", "implement https://github.com/dlang/DIPs/blob/master/DIPs/DIP1008.md" ), + Option("fPIC", + "generate position independent code", + TargetOS.linux + ), Option("g", - "add symbolic debug info" + "add symbolic debug info", + `$(WINDOWS + Add CodeView symbolic debug info with + $(LINK2 $(ROOT_DIR)spec/abi.html#codeview, D extensions) + for debuggers such as + $(LINK2 http://ddbg.mainia.de/releases.html, Ddbg) + ) + $(UNIX + Add symbolic debug info in Dwarf format + for debuggers such as + $(D gdb) + )`, ), Option("gf", "emit debug info for all referenced types" @@ -181,10 +292,14 @@ struct Usage "add stack stomp code" ), Option("H", - "generate 'header' file" + "generate 'header' file", + `Generate $(RELATIVE_LINK2 $(ROOT_DIR)interface-files, D interface file)`, ), Option("Hd=", - "write 'header' file to directory" + "write 'header' file to directory", + `Write D interface file to $(I dir) directory. $(SWLINK -op) + can be used if the original package hierarchy should + be retained.`, ), Option("Hf=", "write 'header' file to filename" @@ -205,19 +320,44 @@ struct Usage "ignore unsupported pragmas" ), Option("inline", - "do function inlining" + "do function inlining", + `Inline functions at the discretion of the compiler. + This can improve performance, at the expense of making + it more difficult to use a debugger on it.`, ), Option("J=", - "look for string imports also in directory" + "look for string imports also in directory", + `Where to look for files for + $(LINK2 $(ROOT_DIR)spec/expression.html#ImportExpression, $(I ImportExpression))s. + This switch is required in order to use $(I ImportExpression)s. + $(I path) is a ; separated + list of paths. Multiple $(B -J)'s can be used, and the paths + are searched in the same order.`, ), Option("L=", - "pass linkerflag to link" + "pass linkerflag to link", + `Pass $(I linkerflag) to the + $(WINDOWS linker $(OPTLINK)) + $(UNIX linker), for example,`, ), Option("lib", - "generate library rather than object files" + "generate library rather than object files", + `Generate library file as output instead of object file(s). + All compiled source files, as well as object files and library + files specified on the command line, are inserted into + the output library. + Compiled source modules may be partitioned into several object + modules to improve granularity. + The name of the library is taken from the name of the first + source module to be compiled. This name can be overridden with + the $(SWLINK -of) switch.`, ), Option("m32", "generate 32 bit code", + `$(UNIX Compile a 32 bit executable. This is the default for the 32 bit dmd.) + $(WINDOWS Compile a 32 bit executable. This is the default. + The generated object code is in OMF and is meant to be used with the + $(LINK2 http://www.digitalmars.com/download/freecompiler.html, Digital Mars C/C++ compiler)).`, (TargetOS.all & ~TargetOS.dragonFlyBSD) // available on all OS'es except DragonFly, which does not support 32-bit binaries ), Option("m32mscoff", @@ -225,71 +365,162 @@ struct Usage TargetOS.windows ), Option("m64", - "generate 64 bit code" + "generate 64 bit code", + `$(UNIX Compile a 64 bit executable. This is the default for the 64 bit dmd.) + $(WINDOWS The generated object code is in MS-COFF and is meant to be used with the + $(LINK2 https://msdn.microsoft.com/en-us/library/dd831853(v=vs.100).aspx, Microsoft Visual Studio 10) + or later compiler.`, ), Option("main", - "add default main() (e.g. for unittesting)" + "add default main() (e.g. for unittesting)", + `Add a default $(D main()) function when compiling. This is useful when + unittesting a library, as it enables running the unittests + in a library without having to manually define an entry-point function.`, ), Option("man", - "open web browser on manual page" + "open web browser on manual page", + `$(WINDOWS + Open default browser on this page + ) + $(LINUX + Open browser specified by the $(B BROWSER) + environment variable on this page. If $(B BROWSER) is + undefined, $(B x-www-browser) is assumed. + ) + $(FREEBSD + Open browser specified by the $(B BROWSER) + environment variable on this page. If $(B BROWSER) is + undefined, $(B x-www-browser) is assumed. + ) + $(OSX + Open browser specified by the $(B BROWSER) + environment variable on this page. If $(B BROWSER) is + undefined, $(B Safari) is assumed. + )`, ), Option("map", - "generate linker .map file" + "generate linker .map file", + `Generate a $(TT .map) file`, ), Option("mcpu=", - "generate instructions for architecture identified by 'id'" + "generate instructions for architecture identified by 'id'", + `Set the target architecture for code generation, + where: + $(DL + $(DT ?)$(DD list alternatives) + $(DT baseline)$(DD the minimum architecture for the target platform (default)) + $(DT avx)$(DD + generate $(LINK2 https://en.wikipedia.org/wiki/Advanced_Vector_Extensions, AVX) + instructions instead of $(LINK2 https://en.wikipedia.org/wiki/Streaming_SIMD_Extensions, SSE) + instructions for vector and floating point operations. + Not available for 32 bit memory models other than OSX32. + ) + $(DT native)$(DD use the architecture the compiler is running on) + )`, ), Option("mcpu=?", "list all architecture options" ), Option("mscrtlib=", "MS C runtime library to reference from main/WinMain/DllMain", - TargetOS.windows + "If building MS-COFF object files with -m64 or -m32mscoff, embed a reference to + the given C runtime library $(I libname) into the object file containing `main`, + `DllMain` or `WinMain` for automatic linking. The default is $(TT libcmt) + (release version with static linkage), the other usual alternatives are + $(TT libcmtd), $(TT msvcrt) and $(TT msvcrtd). + If $(I libname) is empty, no C runtime library is automatically linked in.", + TargetOS.windows, ), Option("mv==", - "use as source file for " + "use as source file for ", + `Use $(I path/filename) as the source file for $(I package.module). + This is used when the source file path and names are not the same + as the package and module hierarchy. + The rightmost components of the $(I path/filename) and $(I package.module) + can be omitted if they are the same.`, ), Option("noboundscheck", - "no array bounds checking (deprecated, use -boundscheck=off)" + "no array bounds checking (deprecated, use -boundscheck=off)", + `Turns off all array bounds checking, even for safe functions. $(RED Deprecated + (use $(TT $(SWLINK -boundscheck)=off) instead).)`, ), Option("O", - "optimize" + "optimize", + `Optimize generated code. For fastest executables, compile + with the $(TT $(SWLINK -O) $(SWLINK -release) $(SWLINK -inline) $(SWLINK -boundscheck)=off) + switches together.`, ), Option("o-", - "do not write object file" + "do not write object file", + `Suppress generation of object file. Useful in + conjuction with $(SWLINK -D) or $(SWLINK -H) flags.` ), Option("od=", - "write object & library files to directory" + "write object & library files to directory", + `Write object files relative to directory $(I objdir) + instead of to the current directory. $(SWLINK -op) + can be used if the original package hierarchy should + be retained`, ), Option("of=", - "name output file to filename" + "name output file to filename", + `Set output file name to $(I filename) in the output + directory. The output file can be an object file, + executable file, or library file depending on the other + switches.` ), Option("op", - "preserve source path for output files" + "preserve source path for output files", + `Normally the path for $(B .d) source files is stripped + off when generating an object, interface, or Ddoc file + name. $(SWLINK -op) will leave it on.`, ), Option("profile", "profile runtime performance of generated code" ), Option("profile=gc", - "profile runtime allocations" + "profile runtime allocations", + `$(LINK2 http://www.digitalmars.com/ctg/trace.html, profile) + the runtime performance of the generated code. + $(UL + $(LI $(B gc): Instrument calls to memory allocation and write a report + to the file $(TT profilegc.log) upon program termination.) + )`, ), Option("release", - "compile release version" + "compile release version", + `Compile release version, which means not emitting run-time + checks for contracts and asserts. Array bounds checking is not + done for system and trusted functions, and assertion failures + are undefined behaviour.` + ), + Option("run ", + "compile, link, and run the program srcfile", + `Compile, link, and run the program $(I srcfile) with the + rest of the + command line, $(I args...), as the arguments to the program. + No .$(OBJEXT) or executable file is left behind.` ), Option("shared", - "generate shared library (DLL)" + "generate shared library (DLL)", + `$(UNIX Generate shared library) + $(WINDOWS Generate DLL library)`, ), Option("transition=", - "help with language change identified by 'id'" + "help with language change identified by 'id'", + `Show additional info about language change identified by $(I id)`, ), Option("transition=?", "list all language changes" ), Option("unittest", - "compile in unit tests" + "compile in unit tests", + `Compile in $(LINK2 spec/unittest.html, unittest) code, turns on asserts, and sets the + $(D unittest) $(LINK2 spec/version.html#PredefinedVersions, version identifier)`, ), Option("v", - "verbose" + "verbose", + `Enable verbose output for each compiler pass`, ), Option("vcolumns", "print character (column) numbers in diagnostics" @@ -300,26 +531,31 @@ struct Usage Option("verrors=spec", "show errors from speculative compiles such as __traits(compiles,...)" ), - Option("vgc", - "list all gc allocations including hidden ones" - ), - Option("vtls", - "list all variables going into thread local storage" - ), Option("-version", "print compiler version and exit" ), Option("version=", - "compile in version code >= level" + "compile in version code >= level", + `Compile in $(LINK2 $(ROOT_DIR)spec/version.html#version, version level) >= $(I level)`, ), Option("version=", - "compile in version code identified by ident" + "compile in version code identified by ident", + `Compile in $(LINK2 $(ROOT_DIR)spec/version.html#version, version identifier) $(I ident)` + ), + Option("vgc", + "list all gc allocations including hidden ones" + ), + Option("vtls", + "list all variables going into thread local storage" ), Option("w", - "warnings as errors (compilation will halt)" + "warnings as errors (compilation will halt)", + `Enable $(LINK2 $(ROOT_DIR)/warnings.html, warnings)` ), Option("wi", - "warnings as messages (compilation will continue)" + "warnings as messages (compilation will continue)", + `Enable $(LINK2 warnings.html, informational warnings (i.e. compilation + still proceeds normally))`, ), Option("X", "generate JSON file"