Please consider that this intrusive sentence could instead be proclaiming that you help sponsor this research.
Home > Programming > Tools > Visual C++ > Compiler > Command-Line Syntax
Each option begins with a switch character, which can be either a forward slash or hyphen. The standard practice in these notes (as also of the product documentation and of CL itself both for command-line errors and warnings and in the summary produced by the /help option) is to use the forward slash in all references to CL options, leaving it as understood that the hyphen is equivalent unless otherwise stated.
Some CL options that begin with the same letter or letters after the switch character can be combined into one command-line token, with the switch character and common letters given just the once. For example, the sequence of options /Ob2 /Og /Oi /Ot /Oy can be compressed to /Ob2gity. Such combined options are just a convenient shorthand. CL unpicks the combination to recover the individual options, which are thereafter treated as if they actually had been given individually. Only individual options are discussed henceforth.
An alphabetical list of individual CL options is given separately and leads to notes for each option. Those notes assume familiarity with the general notes given here.
Some options have a negation whose only difference from the ordinary option is a trailing hyphen. For example, /GR enables a feature (namely, Run-Time Type Information) and /GR- disables that same feature. Not all these negations are noted in the product documentation.
A handful of options allow or require a keyword, which is to follow immediately after a colon. Indeed, the only examples are /clr and /Zc. The first may be given alone or as /clr:noAssembly (or with a negation, albeit undocumented). The second is invalid without a keyword (which may be either forScope or wchar_t).
Though these notes set out to treat these negations and keywords as variations of the underlying option, presuming this to simplify the concept, it is as well to bear in mind that the implementation in CL.EXE actually parses them as separate options. Thus, a /clr or /Zc with a colon and an unrecognised keyword is rejected as an unknown option (with warning D4002), not as an incorrect formulation of a recognised option.
In general, CL options and their keywords are case-sensitive. For example, /GR and /Gr are very different options (one to enable Run-Time Type Information, as noted above, the other to set a default calling convention).
Exceptions are very few. True case-insensitivity applies to just one option, namely /clr (including if given as a negation or with a keyword). One other option, namely /help, is partly case-insensitive in that it is recognised equivalently whether all in lower case or all in upper case.
Some options accept or require an argument. It is always permitted that the argument be the remainder of the command-line token that starts the option.
For example, the command cl test.cpp /Fatest.asm has CL compile the source file “test.cpp”, with the /Fa option directing that an assembly-language listing file named “test.asm” be produced as a by-product.
White space within a command-line token is part of the argument, even at what might be thought to be the start of the argument. Continuing the example, if “test.asm” is the name wanted for the listing file, then there can be no space after the /Fa, even if quoted: the command cl test.cpp "/Fa test.asm" would name the listing file as “ test.asm”, with a leading space. Without the quotes, as cl test.cpp /Fa test.asm, the /Fa and the “test.asm” would be separate command-line tokens, and CL would try to interpret “test.asm” as naming a (second) source file.
For some options, the argument may be given as the next command-line token, provided that this does not begin with a switch character.
For example, the command cl test.cpp /FI test.h has CL compile the source file “test.cpp”, with the /FI option directing that a header file named “test.h” be forcibly included in the compilation. The unquoted white space between the /FI and the “test.h” is optional, and may be thought to improve readability. In the command cl test.cpp /FI /anything, the /FI has no argument within its command-line token but the next command-line token begins with a switch character and is treated by CL as an option, leaving /FI without an argument.
For some more options, the argument may be given as the next command-line token, even if this begins with a switch character.
For example, the command cl test.cpp /I include has CL compile the source file “test.cpp”, with the /I option directing that “include” be added to the search path for header files. Again, the unquoted white space is optional. In the command cl test.cpp /I /anything, the /anything is treated as the argument for /I even though it might be a valid option and have been intended as an option by the programmer.
For one option, specifically /link, the argument is the remainder of the command-line token that starts the option and then all the command-line tokens that follow.
Almost all options that accept an argument (the exceptions being /D, /link, /Tc, /To, /Tp and /U) have in common a maximum length for the argument. For the present implementation, this maximum is 1024 characters. Exceeding it causes error D2038, which will not be mentioned in the syntax notes for particular options (and, indeed, is not an error that the product documentation mentions anywhere).
It is an error (D2004) if an option that requires an argument is given without one. This also is so general a feature of option arguments that it will not be mentioned in the syntax notes for particular options (and, again, is something that the product documentation seems not to mention anywhere).
WORK STILL VERY MUCH IN PROGRESS FROM HERE DOWN
The standard notation for a numerical argument is decimal, with a sign prefix allowed immediately before the first digit. A numerical argument in this notation may be preceded, within its command-line token, by any amount of white space, including none.
Some options permit other notations in which the number has a prefix that sets the base as octal, decimal or hexadecimal. The prefix is 0x for hexadecimal, 0d or 0t for decimal and 0 alone for octal. The prefix is case-insensitive, as are hexadecimal digits. The number begins immediately after the prefix and is formed from all the subsequent characters that are valid digits for the selected base. This form for numerical arguments is not recognised if preceded by white space.
Numbers are evaluated as unsigned 32-bit integers. If the number as given is too large for 32 bits, it is coerced to 0xFFFFFFFF without complaint.
It is an error (D2021) if the command-line token that contains a numerical argument continues beyond the number, including with white space.
Each option may have a list of options that it overrides, another of options it is incompatible with, and another of options that are prerequisites. These lists define the option’s syntactic relations with other options. The compiler builds a set of active options by working through the options as given and applying the relations to determine whether each additional option duplicates, overrides or is incompatible with whatever options have so far been accepted. At the end of this processing, each active option is tested for whether its prerequisites are met among the other active options.
This page was created on 29th October 2005 and was last modified on 5th May 2006.
Copyright © 2005-2006. Geoff Chappell. All rights reserved.
Please consider that this intrusive sentence could instead be proclaiming that you help sponsor this research.
Home > Programming > Tools > Visual C++ > Compiler > Command-Line Syntax
[Home][Programming Samples][Application Notes][Security Notes][Editorial][Consultation][Contacts]