Using Build Tools

The QuickSharp IDE includes a flexible and extensible system for configuring and running build tools such as compilers, interpreters and runtime environments. As supplied, it includes build tool plugins for C#, VB.NET and JScript compilers and support for several Framework SDK utilities. Each of these tools is supplied with a default configuration but this can be modified and supplemented with additional configurations to suit the needs of your development projects.

Understanding build tools

The basic behaviour of a build tool is defined by its plugin which defines the document types, actions and configuration properties supported by the tool.

The document type is the file extension supported by the build tool. For a C# compiler the document type is '.cs', for a VB.NET compiler it is '.vb' and so on. The document type associates a build tool with the source files it is responsible for building.

An action is the operation performed by the build tool; by default QuickSharp supports two actions, compile and run. These are represented by the corresponding menus and toolbar buttons and each build tool will respond to these depending on the actions it has registered with the build system. For the C# build tools, the compiler will respond to the compile action and the runtime target (in this case 'Windows Executable') to the run action.

Whenever a document type is active in the editor the tools configured for that type will be made available by the build system. Each document type may have several tools configured for each of the available actions it supports. The available tools may be viewed using the drop-down lists next to each action button on the toolbar. On each menu a selected tool will be indicated, this is the tool that will be launched when the corresponding action button (or equivalent menu option) is used.

If no tool is available for a particular document type and action combination the action button and its drop-down menu button will both be disabled. If the button is disabled but the drop-down is active it means that tools are available but none have been selected. Use the drop-down list to select a tool and the action button will be enabled.

Compile tools

Compilers are the simplest build tools to understand and configure. The compiler takes a source file of the associated document type and transforms it into an output file, in most cases an executable program ('.exe') or a library ('.dll'). In some cases the compile tool is not responsible for producing a program but a data file of some sort; the resource file generator build tool transforms an XML resource file into a binary resource file for embedding in a program.

Where build tools produce an executable output they are paired with a run tool which is responsible for running the program. In the case of the resource file generator only a compile tool is associated with the '.resx' document type; as there is no executable output there is no need for a corresponding run tool.

Run tools

Where a run tool is associated with a compile tool, it will usually take the form of a 'pseudo-tool' in that the tool being run is actually the output of the compile tool. Conversely, if there is no compile stage the run tool will run the source file directly, as in the case of an interpreter such as Python or Ruby.

Just as compile tools are associated with a document type, so too are run tools. In most cases each run tool will run the same type of file, a Windows executable ('.exe') but occasionally a different target may be required such as a runtime interpreter as used by Mono executables.

Even though the compile tools for different document types might produce the same type of output (a Windows '.exe' for example) each document type must have it's own instance of the runtime target. This is because tools are associated with document types not output types; each document must have its own runtime target to ensure it is correctly enabled when the document type becomes active in the editor.

Configuring build tools

Once a build tool has been enabled by a plugin it must be configured for use within QuickSharp. A build tool may have multiple configurations and each may be thought of as a separate instance of the build tool. Each instance will be displayed in the tools drop-down menu associated with the corresponding action button on the toolbar.

Tools are configured in the Build Tools page of the QuickSharp options editor, this lists the currently configured tools. Double-click an item to open the tool configuration editor or right-click and select Edit. Select Delete to remove an item, Clone to make a copy or New to create a new one.

Tool configuration editor

Use the tool configuration editor to create or edit tool configurations, this example shows the debug configuration for the C# 3.0 compiler.

Tool configuration screen shot

The display name determines the text used to present the tool in the action button drop-down lists and the output window title bar when the tool is run.

The file type and action determine when the tool is available and how it will be used. Once these have been defined they cannot be changed.

The path and arguments define how the tool will be run and define the tool's executable file and the parameters passed when it is run. Both may include macros for expansion at run time.

Common options are options passed to the tool at runtime in place of the macro ${COMMON_OPT}.

The output parser is used to interpret the tool's output messages in order to determine if it is reporting an error and if so the location of the error. Output parsers are defined by tool plugins, in most cases a tool will only need a single parser but should a plugin define more than one tool for a single document type multiple parsers may be available.

Build tool macros

The path and argument strings allow macros to be included; these enable runtime information such as the name of the source file to be included in the tool command. There are two kinds of macro: generic and specific. Generic macros are supplied by the build tool system and cover common values such as file names and common options; specific macros are provided by tool plugins and are specific to the individual tools.

Generic macros

The build tool system recognizes the following generic macros:

${SRC_PATH}     source file path
${SRC_FILE}     source file name
${SRC_NAME}     source file name without extension
${SRC_EXT}      source file extension
${OUT_PATH}     output file path
${OUT_FILE}     output file name
${OUT_NAME}     output file name without extension
${OUT_EXT}      output file extension
${IDE_HOME}     QuickSharp installation directory
${USR_HOME}     QuickSharp user data directory
${USR_DOCS}     user's "My Documents" folder
${SYSTEM}       Windows system directory (usually C:\WINDOWS\system32)
${PFILES}       Windows "Program Files" directory
${WORKSPACE}    workspace directory name
${COMMON_OPT}   options provided by the build tool
${EMBEDDED_OPT} options embedded in the source
${RUNTIME_OPT}  runtime arguments embedded in the source

Macros can be embedded in the tool's path and argument strings; the appropriate substitution will be made when the tool is run.

Tool specific macros

Tool specific macros are defined by tool plugins. By default QuickSharp recognizes only one tool specific macro which is defined for use by the .NET compile tools.

${DOTNET_TARGET}

This provides the correct target for a build (for example when compiling a C# file) and translates to '/t:library' or '/t:exe' depending on the content of the source file. If the file contains a valid Main method a executable ('.exe') will be created; if not a library will be produced.