PBShell is entirely command line driven, being designed for invocation from UltraEdit, using text substitution macros (variables) for all or most of the parameters.
PBShell [/S][/D|/X|/E] primary_src[;current_src] [params]
PBShell [/S][/D|/X|/E] ;current_src [params]
|•||where "/S" specifies "test compile". The program will be compiled for syntax checking but no new EXE or DLL will be produced.|
|•||where "/D" specifies "compile and debug". The program will be compiled within the PB IDE then the debugger will be launched.|
|•||where "/X" specifies "compile and run". If the compilation is successful, the compiled program will be launched after compilation.|
|•||where "/E" specifies "run only". The program will not be compiled, but if a compiled version of the program exists, it will be launched.|
|•||where "params" are the command line parameters to be passed to the compiled program if it is requested to run the program (has meaning only if /X or /E is also specified).|
The /S, /D, /X and /E switches are not case sensitive but are mutually exclusive - only one may be specified. If none of /S, /D, /X or /E are specified, the action is "compile only".
Source file(s) may be specified as:
|•||where "primary_src" is the primary source file, with or without a BAS extension, and with or without a path. If this file specification contains spaces it must be enclosed within double quotes (double quotes don't do any harm when used with short file names, so they may be used unconditionally).|
|•||where "current_src" is the current source file. If specified, this should be specified complete with extension as one of it's purposes is to detect whether a resource file is being passed for compilation. It's other purpose is to allow the compilation of a single source file without setting up a project.|
There must be no space either before or after the semicolon, if used, and the semicolon must be outside any double quotes used to enclose the file names. Empty double quotes may be used and means the same as no file specified.
The concept of a "primary source file" does not widely exist outside of a PB environment, and so is not normally explicitly supported by UltraEdit.
The solution is to name the project the same as the primary source file name, store the project file in the same directory as the primary source file, and set the working directory for the tool to the project directory. The tool configuration is then:
Command Line: PBShell "%rn";"%f"
Working Directory: %rp
where "%rn" is the project name, and "%f" is the full path and name of the currently selected file. It is safest to enclose file names in double quotes, just in case they are long file names containing spaces. The current file is specified with full path because if there is no project set up, the project directory will be null or incorrect.
This may, for example, expand as follows
Command Line: PBShell "MyApp";"C:\MyApp\Library\Edit.inc"
Working Directory: C:\MyApp\Source
PBShell will send "C\MyApp\Source\MyApp.bas" to the PB compiler, ignoring (after checking) "Edit.inc".
Now, lets imagine that MyApp.rc is currently selected in the editor, the command line expands to:
Command Line: PBShell "MyApp";"C:\MyApp\Resource\MyApp.rc"
Working Directory: C:\MyApp\Source
PBShell will send "C:\MyApp\Resource\MyApp.rc to the resource compiler, ignoring "MyApp.bas".
If no project is open, but a basic source file is currently selected in the editor:
Command Line: PBShell "";"C:\TestCode\Buttons.bas"
Working Directory: ?
PBShell will send "C:\TestCode\Buttons.bas" to the PB compiler.
This allows for the quick compile of single source file programs without having to set up a project or modify the tool configuration. Note that empty quotes followed by a semicolon, or a leading semicolon, on the command line are treated equivalently by PBShell.
An alternative which has exactly the same effect as the above examples, is to specify the project directory (working directory) as part of the primary file specification. You do not then need to set the working directory:
Command Line: PBShell "%rp\%rn";"%f"
You will need to specify the complete path to PBSHELL.EXE (not shown in the examples here).
More on the /S switch:
When the /S switch is specified the source code is compiled without overwriting the present EXE or DLL file. This is implemented by renaming the target file to a temporary name ($TEMP$.EXE or $TEMP$.DLL) before compilation, deleting the newly compiled file (if it compiled without errors and exists), then renaming the original file back to the target file name after compilation. This will even work if the target EXE is currently running or if the target file does not yet exist. It doesn't require a #COMPILE directive (though this will be used if included) and source code is not modified.