BinPlace Command-Line Syntax
BinPlace uses the following syntax at the command line:
binplace [Options] File [ [Options] [@PlaceFile] File [...] ]
Parameters
- Options
- This can include any of the following switches. The switches should be preceded by a hyphen ( - ) or a slash ( / ). It is possible to combine several options after one hyphen or slash, but options that take additional parameters should be followed by a space. Thus, the following two commands are equivalent:
binplace -q -k -g LCFile -v -s SymbolRoot File
binplace -qkg LCFile -vs SymbolRoot File
The following switches are available:
- -a
- Causes BinPlace to strip private symbols out of the symbol files when they are being placed. This creates stripped symbol files that contain public symbols but not private symbols. When using the -a switch, you must use -s and -x as well. When -a is used, stripped symbol files will be placed in the path specified by -s SymbolRoot. If -n FullSymbolRoot is also present, the full symbol files will be placed in FullSymbolRoot. Otherwise, they will not be placed anywhere.
- -b ExtraSubdirectory
- Causes BinPlace to place files in a different location than usual. After concatenating the root destination directory, the class subdirectory, and the file-type subdirectory as usual, BinPlace will then append ExtraSubdirectory to this path to create the final destination directory. ExtraSubdirectory should neither begin with nor end with a backslash. See BinPlace Destination Directories for more details.
- -e
- Causes BinPlace to continue execution if a file cannot be placed. By default, BinPlace will exit when this error occurs.
- -f
- Forces BinPlace to place a file even if it is overwriting a more recent file. By default, when BinPlace attempts to place a file, it will overwrite an older version but will not overwrite a more recent version.
- -g LCFile
- Causes BinPlace to verify the executable file. LCFile specifies the localization constraint file to be used for this verification.
- -h
- Causes BinPlace to create hard links instead of copying the file when placing files. This option is only available on the NTFS file system.
- -j
- Causes BinPlace to verify that the proper symbols exist before copying any executable files. For this option to be used, the SymChk tool must be in your path. (SymChk is part of the Debugging Tools for Windows package. See Debugging Tools for NT-Based Operating Systems for details.)
- -k
- Causes BinPlace to preserve file attributes. By default, BinPlace will turn off the archive attribute.
- -n FullSymbolRoot
- Specifies the root directory for full symbol files (symbol files that contain both public and private symbols). This requires the -a, -x, and -s switches as well. See BinPlace Destination Directories for more details.
- -o RootSubdirectory
- Specifies a subdirectory of the root destination directory to be used. When the destination directory is created, RootSubdirectory will be inserted after the root destination directory and before the class subdirectory. See BinPlace Destination Directories for more details.
- -p PlaceFile
- Specifies the path and file name of the place file. If the -p switch is omitted, the file specified by the BINPLACE_PLACEFILE environment variable is used as the place file. If neither is present, \tools\placefil.txt is used. See Place File Syntax for an explanation of a place file's contents.
- -q
- Prevents BinPlace from using a log file. If the -q switch is omitted, the file specified by the BINPLACE_LOG environment variable is used as the log file.
- -r RootDestinationPath
- Specifies the root destination directory. If this is omitted, the default is determined by the _NT386TREE, _NTIA64TREE, or _NTAMD64TREE environment variable on an x86, Itanium, or AMD x86-64 computer, respectively. See BinPlace Destination Directories for details.
- -s SymbolRoot
- Specifies the root directory for symbol files. If the -a and -x switches are also used, private symbols will be stripped out of the symbol files, and the stripped symbol files will be placed in the directory specified by SymbolRoot. If you want to place both stripped and full symbol files, you should use -a -x -s SymbolRoot -n FullSymbolRoot. See BinPlace Destination Directories for more details.
- -t
- Test mode. When this switch is used, no files will be copied, but BinPlace will display warning and error messages as if it were placing files. You may want to use the -v switch as well to increase the number of messages.
- -u
- Causes BinPlace to append \up to the class subdirectory. This is useful for separating out uniprocessor (UP) drivers. In addition, whenever this switch is used, BinPlace will not split executable files containing symbols. See BinPlace Destination Directories for more details.
- -v
- Verbose mode. Causes BinPlace to display more detailed error, warning, and progress messages.
- -w
- Causes BinPlace to add Windows 95 symbol files (.sym) to the symbol tree.
- -x
- If BinPlace encounters files that use the old symbol system, this switch causes it to remove all symbols from the executable files and move this information to separate symbol files. See Symbol File Systems for details. When using the -x switch, you must use -s and -a as well.
- -y
- Prevents BinPlace from using any class subdirectories. The destination directory will be created solely from the root destination directory plus the file-type subdirectory. See BinPlace Destination Directories for details.
- -z
- Cancels the -x switch. This can be useful if you are using BinPlace on several targets — you can use a command of the form binplace arguments Target1 arguments Target2, and since the command-line is parsed from left to right, Target1 and Target2 will be affected by different arguments. (See the Comments section following). If a -z switch is encountered, this cancels the effect of any previous -x switch.
- -ci ReturnCode, Application, Argument, Argument, ...
- Causes BinPlace to use a custom application to validate all executable files. You can use the -ci switch if you want BinPlace to use some other application to do its validation.
ReturnCode should be the value that will be returned by this application if it finds an error in an executable file. The additional parameters are used to launch this application. These must all be separated by commas. Application specifies the name of the program. This can be followed by any number of command-line arguments. The program will be started with a command line that includes Application followed by all the arguments (separated by spaces rather than commas), and finally ending with the name of the executable to be checked.
- -:ARC
- Causes BinPlace to only place files whose archive attributes are set.
- -:DBG
- Prevents BinPlace from placing .dbg files. If the -j switch is also used, this will prevent BinPlace from placing binaries that point to .dbg files. For this option to be used, the SymChk tool must be in your path. (SymChk is part of the Debugging Tools for Windows package. See Debugging Tools for NT-Based Operating Systems for details.)
- -:DEST ClassPath
- Causes BinPlace to ignore the place file and use the specified ClassPath as the class subdirectory. See BinPlace Destination Directories for details.
- -:LOGPDB
- Causes BinPlace to include the full .pdb paths in the log file.
- -:REN NewName
- Causes BinPlace to rename the files being placed. The original file name, including the extension, will be replaced by NewName. (If the original file is an executable file that is being split, the new symbol file will be given the original file name plus the extension .dbg.)
- -ChangeAsmsToRetailForSymbols
- Causes BinPlace to replace the string "asms" with the string "retail" if it occurs in the destination directory for symbol files. See BinPlace Destination Directories for more details.
- File
- Specifies the full path and file name of a file that BinPlace will act on. You can list any number of files, separated by spaces. If a path and file name contains a space, you must enclose the path and file name in quotation marks.
- @PlaceFile
- If any file name is preceded by an at sign ( @ ), the file name represents the name of a place file. For more information, see the following Comments section.
Comments
BinPlace parses the command line from left to right. You can specify several options, then a File parameter, then new options, then another File parameter, and so forth. Each time BinPlace encounters a new option, it will be adopted, overriding any previously seen contradictory options. Whenever it encounters a File specifier, it will act on that file using the accumulated options it has already encountered on the command line.
It is possible to pass parameters to BinPlace from a text file. There are two ways to do this:
- You can specify a file name in the BINPLACE_OVERRIDE_FLAGS environment variable. This file will be read and its contents used as parameters whenever BinPlace is run. The parameters in this file will be parsed before the parameters that actually appear on the BinPlace command line.
- You can specify a file name on the BinPlace command line by prefixing it with an at sign ( @ ). When BinPlace sees a string beginning with this sign on its command line, it will take the string, remove the at sign, and then look for a file with this name. If it finds this file, it will insert its text into the command line at exactly the place where the original parameter beginning with the at sign had been. Because BinPlace parses parameters from left to right, you can use this technique along with multiple instances of File to use BinPlace on several files with different options for each, without having to type all the options each time. (If this file is not found, BinPlace will treat the original string, including the at sign, as a File parameter.)
