17.  Command Line Interface

The Dynamic C command line compiler (dccl_cmp.exe) performs the same compilation and program execution as its GUI counterpart (dcrabxx.exe), but is invoked as a console application from a DOS window. It is called with a single source file program pathname as the first parameter, followed by optional case-insensitive switches that alter the default conditions under which the program is run. The results of the compilation and execution, all errors, warnings and program output, are directed to the console win­dow and are optionally written or appended to a text file.

Note that the command line compiler resides in the directory where you installed Dynamic C. In the con­sole window, you need to "cd" into the directory where the command line compiler resides. From there you must type in the relative path of the sample you want to compile. Quotes are need if there are spaces in the path. For example,

> cd c:\DCRabbit_10.40
> dccl_cmp samples\memory_usage.c
> dccl_cmp "c:\My Documents\my program.c"

17.1 Default States

The command line compiler uses the values of the environment variables that are in the project file indi­cated by the -pf switch, or if the -pf switch is not used, the values are taken from default.dcp. For more information, please see Chapter 18, “Project Files” on page 322.

The command line compiler will compile and run the specified source file. The exception to this is when the project file “Default Compile Mode” is one of the options which compiles to a .bin file, in which case the command line compiler will not run the program but will only compile the source to a .bin file. Com­mand line help displayed to the console with

dccl_cmp

gives a summary of switches with defaults from the default project file, default.dcp, and

dccl_cmp -pf specified_project_name.dcp

gives a summary of switches with defaults from the specified project file. All project options including the default compile mode can be overridden with the switches described in Section 17.4.

17.2 User Input

Applications requiring user input must be called with the -i option:

dccl_cmp myProgram.c -i myProgramInputs.txt

where myProgramInputs.txt is a text file containing the inputs as separate lines, in the order in which myProgram.c expects them.

17.3 Saving Output to a File

The output consists of all program printf’s as well as all error and warning messages.

Output to a file can be accomplished with the -o option

dccl_cmp myProgram.c -i myProgramInputs.txt -o myOutputs.txt

where myOutputs.txt is overwritten if it exists or is created if it does not exist.

If the -oa option is used, myOutputs.txt is appended if it exists or is created if it does not.

17.4 Command Line Switches

Each switch must be separated from the others on the command line with at least one space or tab. Extra spaces or tabs are ignored. The parameter(s) required by some switches must be added as separate text immediately following the switch. Any of the parameters requiring a pathname, including the source file pathname, can have imbedded spaces by enclosing the pathname in quotes.

17.4.1  Switches Without Parameters

-b

Description:

Use compile mode: Compile to .bin file using attached target.

Factory Default:

Compile mode: Compile to attached target.

GUI Equivalent:

Compile program (F5) with Default Compile Mode set to "Compile to .bin file using attached target" in Compiler tab of Project Options dialog.

-bf-

Description:

Undo user-defined BIOS file specification.

Factory Default:

None.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Compiler tab of Project Options dialog. Uncheck the “User Defined BIOS File” checkbox.

-br

Description:

Use compile mode: Compile defined target configuration to .bin file

Factory Default:

Compile mode: Compile to attached target.

GUI Equivalent:

Compile program (F5) with Default Compile Mode set to "Compile defined target configuration to .bin file" in Compiler tab of Project Options dialog.

-d+

Description:

Enable automatic detection of internal RAM.

Factory Default:

Internal RAM will be automatically detected.

GUI Equivalent:

None.

-d-

Description:

Disable automatic detection of internal RAM. Set to false only for Rabbit 4000 CPUs.

Factory Default:

Internal RAM will be automatically detected.

GUI Equivalent:

None.

-h+

Description:

Print program header information.

Factory Default:

No header information will be printed.

GUI Equivalent:

None.

Example:

dccl_cmp samples\demo1.c -h -o myoutputs.txt

Header text preceding output of program:

********************************************************
4/5/01   2:47:16 PM
dccl_cmp.exe, Version 10.40P - English
samples\demo1.c
Options: -h+ -o myoutputs.txt
Program outputs:

Note: Version information refers to dcwd.exe with the same compiler core.

-h-

Description:

Disable printing of program header information.

Factory Default:

No header information will be printed.

GUI Equivalent:

None.

-id+

Description:

Enable separate instruction and data space.

Factory Default:

Separate I&D space is disabled.

GUI Equivalent:

Check “Separate Instruction & Data Space” in Project Options | Compiler.

-id-

Description:

Disable separate instruction and data space.

Factory Default:

Separate I&D space is disabled.

GUI Equivalent:

Uncheck “Separate Instruction & Data Space” in the Project Options | Compiler dialog box.

-ini

Description:

Generates inline code for WrPortI(), RdPortI(), BitWrPortI() and BitRdPortI() if all arguments are constants.

Factory Default:

No inline code is generated for these functions.

GUI Equivalent:

Check “Inline builtin I/O functions” in the Project Options | Compiler dialog box.

-lf-

Description:

Undo Library Directory file specification.

Factory Default:

No Library Directory file is specified.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Uncheck “User Defined Lib Directory File.”

-mf

Description:

Memory BIOS setting: Flash.

Factory Default:

Memory BIOS setting: Flash.

GUI Equivalent:

Select “Code and BIOS in Flash” in the Project Options | Compiler dialog box.

-mfr

Description:

The BIOS and code are compiled to flash, and then the BIOS copies the flash image to RAM to run the code.

Factory Default:

Memory BIOS setting: Flash

GUI Equivalent:

Select “Code and BIOS in Flash, Run in RAM” in the Project Options | Compiler dialog box.

-mr

Description:

Memory BIOS setting: RAM.

Factory Default:

Memory BIOS setting: Flash.

GUI Equivalent:

Select “Code and BIOS in RAM” in the Project Options | Compiler dialog box.

-n

Description:

Null compile for errors and warnings without running the program. The program will be downloaded to the target.

Factory Default:

Program is run.

GUI Equivalent:

Select Compile | Compile or use the keyboard shortcut <F5>.

-r

Description:

Use compile mode: Compile to attached target.

Factory Default:

Compile mode: Compile to attached target.

GUI Equivalent:

Run program (F9)

-rb+

Description:

Include BIOS when compiling to a file.

Factory Default:

BIOS is included if compiling to a file.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Check “Include BIOS.”

-rb-

Description:

Do not include BIOS when compiling to a file.

Factory Default:

BIOS is included if compiling to a file.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Uncheck “Include BIOS.”

-rd+

Description:

Include debug code when compiling to a file.

Factory Default:

RST 28 instructions are included

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Select “Always” or “Auto...” under “Include RST 28 instructions.”

-rd-

Description:

Do not include debug code when compiling to a file. This option is ignored if not compiling to a file.

Factory Default:

RST 28 instructions are included.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Select “Never, disables debugging” under “Include RST 28 instructions.”

-ri+

Description:

Enable runtime checking of array indices.

Factory Default:

Runtime checking of array indices is performed.

GUI Equivalent:

Check “Array Indices” in the Project Options | Compiler dialog box.

 

-ri-

Description:

Disable runtime checking of array indices.

Factory Default:

Runtime checking of array indices is performed.

GUI Equivalent:

Uncheck “Array Indices” in the Project Options | Compiler dialog box.

 

-rp+

Description:

Enable runtime checking of pointers.

Factory Default:

Runtime checking of pointers is performed.

GUI Equivalent:

Check “Pointers” in the Project Options | Compiler dialog box.

-rp-

Description:

Disable runtime checking of pointers.

Factory Default:

Runtime checking of pointers is performed.

GUI Equivalent:

Uncheck “Pointers” in the Project Options | Compiler dialog box.

-rw+

Description:

Restrict watch expressions—may save root code space.

Factory Default:

Allow any expressions in watch expressions.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Check “Restrict watch expressions . . .”

-rw-

Description:

Don’t restrict watch expressions.

Factory Default:

Allow any expressions in watch expressions.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Check “Allow any expressions in watch expressions”

-sp

Description:

Optimize code generation for speed.

Factory Default:

Optimize for speed.

GUI Equivalent:

Choose “Speed” in the Project Options | Compiler dialog box.

-sz

Description:

Optimize code generation for size.

Factory Default:

Optimize for speed.

GUI Equivalent:

Choose “Size” in the Project Options | Compiler dialog box.

-td+

Description:

Enable type demotion checking.

Factory Default:

Type demotion checking is performed.

GUI Equivalent:

Check “Demotion” in the Project Options | Compiler dialog box.

-td-

Description:

Disable type demotion checking.

Factory Default:

Type demotion checking is performed.

GUI Equivalent:

Uncheck “Demotion” in the Project Options | Compiler dialog box.

-tp+

Description:

Enable type checking of pointers.

Factory Default:

Type checking of pointers is performed.

GUI Equivalent:

Check “Pointer” in the Project Options | Compiler dialog box.

-tp-

Description:

Disable type checking of pointers.

Factory Default:

Type checking of pointers is performed.

GUI Equivalent:

Uncheck “Pointer” in the Project Options | Compiler dialog box.

-tt+

Description:

Enable type checking of prototypes.

Factory Default:

Type checking of prototypes is performed.

GUI Equivalent:

Check “Prototype” in the Project Options | Compiler dialog box.

-tt-

Description:

Disable type checking of prototypes.

Factory Default:

Type checking of prototypes is performed.

GUI Equivalent:

Uncheck “Prototype” in the Project Options | Compiler dialog box.

-vp+

Description:

Verify the processor by enabling a DSR check. This should be disabled if a check of the DSR line is incompatible on your system for any reason.

Factory Default:

Processor verification is enabled.

GUI Equivalent:

Check “Enable Processor verification” in the Project Options | Communications dialog box.

-vp-

Description:

Assume a valid processor is connected.

Factory Default:

Processor verification is enabled.

GUI Equivalent:

Uncheck “Enable Processor verification” in the Project Options | Communications dialog box.

-wa

Description:

Report all warnings.

Factory Default:

All warnings reported.

GUI Equivalent:

Select “All” under “Warning Reports” in the Project Options | Compiler dialog box.

-wn

Description:

Report no warnings.

Factory Default:

All warnings reported.

GUI Equivalent:

Select “None” under “Warning Reports” in the Project Options | Compiler dialog box.

-ws

Description:

Report only serious warnings.

Factory Default:

All warnings reported.

GUI Equivalent:

Select “Serious Only” under “Warning Reports” in the Project Options | Compiler dialog box.

17.4.2  Switches Requiring a Parameter

The following switches require one or more parameters.

-bf BIOSFilePathname

Description:

 Compile using a BIOS file found in BIOSFilePathname.

Factory Default:

 \Bios\RabbitBios.c

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Check the box under “User Defined BIOS File” and then fill in the pathname for the new BIOS file.

Example:

dccl_cmp myProgram.c -bf MyPath\MyBIOS.lib

-clf ColdLoaderFilePathname

Description:

Compile using cold loader file found in ColdLoaderFilePathname.

Factory Default:

\Bios\ColdLoad.bin

GUI Equivalent:

None.

Example:

dccl_cmp myProgram.c -clf MyPath\MyColdloader.bin

-d MacroDefinition

Description:

Define macros and optionally equate to values. The following rules apply and are shown here with examples and equivalent #define form:

Separate macros with semicolons.

dccl_cmp myProgram.c -d DEF1;DEF2
#define DEF1
#define DEF2

A defined macro may be equated to text by separating the defined macro from the text with an equal sign (=).

dccl_cmp myProgram.c -d DEF1=20;DEF2
#define DEF1 20
#define DEF2

Macro definitions enclosed in quotation marks will be interpreted as a single command line parameter.

dccl_cmp myProgram.c -d “DEF1=text with spaces;DEF2”
#define DEF1 text with spaces
#define DEF2

A backslash preceding a character will be kept except for semicolon, quote and backslash, which keep only the character following the backslash. An escaped semicolon will not be interpreted as a macro separator and an escaped quote will not be interpreted as the quote defining the end of a command line parameter of text.

dccl_cmp myProgram.c -d DEF1=statement\;;ESCQUOTE=\\\”
#define DEF1 statement;
#define ESCQUOTE \”
dccl_cmp myProg.c -d “FSTR = \”Temp = %6.2F DEGREES C\n\””
#define FSTR “Temp = %6.2f degrees C\n”

Factory Default:

None.

GUI Equivalent:

Select the Defines tab from Project Options.

-d- MacroToUndefine

Description:

Undefines a macro that might have been defined in the project file. If a macro is defined in the project file read by the command line compiler and the same macro name is redefined on the command line, the command line definition will generate a warning. A macro previously defined must be undefined with the -d- switch before redefining it. Undefining a macro that has not been defined has no consequence and so is always safe although possibly unnecessary. In the example, all compilation settings are taken from the project file specified except that now the macro MAXCHARS was first undefined before being redefined.

Factory Default:

None.

GUI Equivalent:

None.

Example:

dccl_cmp myProgram.c -pf myproject -d- MAXCHARS -d MAXCHARS=512

-eto EthernetResponseTimeout

Description:

Time in milliseconds Dynamic C waits for a response from the target on any retry while trying to establish Ethernet communication.

Factory Default:

8000 milliseconds.

GUI Equivalent:

None.

Example:

dccl_cmp myProgram.c -eto 6000

-i InputsFilePathname

Description:

Execute a program that requires user input by supplying the input in a text file. Each input required should be entered into the text file exactly as it would be when entered into the Stdio Window in dcwd.exe. Extra input is ignored and missing input causes dccl_cmp to wait for keyboard input at the command line.

Factory Default:

None.

GUI Equivalent:

Using -i is like entering inputs into the Stdio Window.

Example

dccl_cmp myProgram.c -i MyInputs.txt

-lf LibrariesFilePathname

Description:

Compile using a file found in LibrariesFilePathname which lists all libraries to be made available to your programs.

Factory Default:

Lib.dir.

GUI Equivalent:

This is an advanced setting, viewable by clicking on the “Advanced” radio button at the bottom of the Project Options | Compiler dialog box. Check the box under “User Defined Lib Directory File” and then fill in the pathname for the new Lib.dir.

Example

dccl_cmp myProgram.c -lf MyPath\MyLibs.txt

-ne maxNumberOfErrors

Description:

Change the maximum number of errors reported.

Factory Default:

A maximum of 10 errors are reported.

GUI Equivalent:

Enter the maximum number of errors to report under “Max Shown” in the Project Options | Compiler dialog box.

Example:

Allows up to 25 errors to be reported:

dccl_cmp myProgram.c -ne 25

-nw maxNumberOfWarnings

Description:

Change the maximum number of warnings reported.

Factory Default:

A maximum of 10 warnings are reported.

GUI Equivalent:

Enter the maximum number of warnings to report under “Max Shown” in the Project Options | Compiler dialog box.

Example:

Allows up to 50 warnings to be reported:

dccl_cmp myProgram.c -nw 50

-o OutputFilePathname

Description:

Write header information (if specified with -h) and all program errors, warnings and outputs to a text file. If the text file does not exist it will be created, otherwise it will be overwritten.

Factory Default:

None.

GUI Equivalent:

Go to Option | Environment Options and select the Debug Windows tab. Under “Specific Preferences” select “Stdio” and check “Log to File” under “Options.”

Example

dccl_cmp myProgram.c -o MyOutput.txt
dccl_cmp myProgram.c -o MyOutput.txt -h
dccl_cmp myProgram.c -h -o MyOutput.txt

-oa OutputFilePathname

Description:

Append header information (if specified with -h) and all program errors, warnings and outputs to a text file. If the text file does not exist it will be created, otherwise it will be appended.

Factory Default:

None.

GUI Equivalent:

Go to Option | Environment Options and select the Debug Windows tab. Under “Specific Preferences” select “Stdio” and check “Log to File” under “Options,” then check “Append” and specify the filename.

Example

dccl_cmp myProgram.c -oa MyOutput.txt

-pbf PilotBIOSFilePathname

Description:

Compile using a pilot BIOS found in PilotBIOSFilePathname.

Factory Default:

\Bios\Pilot.bin

GUI Equivalent:

None.

Example:

dccl_cmp myProgram.c -pbf MyPath\MyPilot.bin

-pf projectFilePathname

Description:

Specify a project file to read before the command line switches are read. The environment settings are taken from the project file specified with -pf, or default.dcp if no other project file is specified. Any switches on the command line, regardless of their position relative to the -pf switch, will override the settings from the project file.

Factory Default:

The project file default.dcp.

GUI Equivalent:

Select File | Project | Open...

Example

dccl_cmp myProgram.c -ne 25 -pf myProject.dcp
dccl_cmp myProgram.c -ne 25 -pf myProject

Note: The project file extension, .dcp, may be omitted.

-ret Retries

Description:

The number of times Dynamic C attempts to establish communication if the given timeout period expires.

Factory Default:

3

GUI Equivalent:

None.

Example:

dccl_cmp myProgram.c -ret 5

-rf RTIFilePathname

Description:

Compile to a .bin file using targetless compilation parameters found in RTIFilePathname. The resulting compiled file will have the same pathname as the source (.c) file being compiled, but with a .bin extension.

Factory Default:

None.

GUI Equivalent:

 

Example:

dccl_cmp myProgram.c -rf MyTCparameters.rti
dccl_cmp myProgram.c -rf “My Long Pathname\MyTCparameters.rti”

-rti BoardID:CpuID:CrystalSpeed:RAMSize:FlashSize

Description:

Compile to a .bin file using parameters defined in a colon separated format of BoardID:CpuID:CrystalSpeed:RAMSize:FlashSize. The resulting compiled file will have the same pathname as the source (.c) file being compiled, but with a .bin extension.

BoardID - Hex integer

CpuID - 4000r# or 5000r# where # is the revision number of the CPU:
              4000r0: corresponds to UL1T/JCT1T
              5000r0: corresponds to XYZ1T/ABC1T/CBS1T

(The file TCData.ini in the root installation directory for Dynamic C identifies all current CPU identifiers.)

CrystalSpeed - Base frequency, decimal floating point, in MHz
RAMSize - Decimal, in KBytes
FlashSize - Primary flash, decimal, in KBytes.

Factory Default:

None.

GUI Equivalent:

Select Options | Project Options | Targetless | Board Selection and choose a board from the list; then select Compile | Compile to .bin File | Compile to Flash

Example:

dccl_cmp myProgram.c -rti 0x0700:2000r3:11.0592:512:256

-s Port:Baud:Stopbits

Description:

Use serial transmission with parameters defined in a colon separated format of Port:Baud:Stopbits:BackgroundTx.

Port: 1, 2, 3, 4, 5, 6, 7, 8

Baud: 110, 150, 300, 600, 1200, 2400, 4800, 9600, 12800, 14400, 19200, 28800, 38400, 57600, 115200, 128000, 230400, 256000

Stopbits: 1, 2

Include all serial parameters in the prescribed format even if only one is being changed.

Factory Default:

1:115200:1:0

GUI Equivalent:

Select the Communications tab of Project Options. Select the “Use Serial Connection” radio button.

Example:

Changing port from default of 1 to 2:

dccl_cmp myProgram.c -s 2:115200:1:0

-sto SerialResponseTimeout

Description:

Time in milliseconds Dynamic C waits for a response from the target on any retry while trying to establish serial communication.

Factory Default:

300 ms.

GUI Equivalent:

None.

Example:

dccl_cmp myProgram.c -sto 400

17.5 Examples

The following examples illustrate using multiple command line switches at the same time. If the switches on the command line are contradictory, such as -mr and -mf, the last switch (read left to right) will be used.

Example 1

In this example, all current settings of default.dcp are used for the compile.

dccl_cmp samples\timerb\timerb.c

Example 2

In this example, all settings of myproject.dcp are used, except timer_b.c is compiled to timer_b.bin instead of to the target and warnings or errors are written to myouputs.txt.

dccl_cmp samples\timerb\timer_b.c -o myoutputs.txt -b -pf myproject

Example 3

These examples will compile and run myProgram.c with the current settings in default.dcp but using different defines, displaying up to 50 warnings and capture all output to one file with a header for each run.

dccl_cmp myProgram.c -d MAXCOUNT=99 -nw 50 -h -o myOutput.txt
dccl_cmp myProgram.c -d MAXCOUNT=15 -nw 50 -h -oa myOutput.txt
dccl_cmp myProgram.c -d MAXCOUNT=15 -d DEF1 -nw 50 -h -oa myOutput.txt

The first run could have used the -oa option if myOutput.txt were known to not initially exist. myProgram.c presumably uses a constant MAXCOUNT and contains one or more compiler directives that react to whether or not DEF1 is defined.

17.6 Command Line RFU

There is also a command line version of the RFU. On the command line specify:

clRFU SourceFilePathName [options]

where SourceFilePathName is the path name of the .bin file to load to the connected target. The options are as follows:

-cl ColdLoaderPathName

Description:

Select a new initial loader.

Default:

\bios\coldload.bin

RFU GUI Equivalent:

From the Setup | Boot Strap Loaders dialog box, type in a pathname or click on the ellipses radio button to browse for a file.

Example:

clRFU myProgram.bin -cl myInitialLoader.bin

-fi Flash.ini PathName

Description:

Select a new file that Dynamic C will use to externally define flash.

Default:

flash.ini

RFU GUI Equivalent:

From the “Choose File Locations...” dialog box, visible by selecting Setup | File Locations, type in a pathname or click on the ellipses radio button to browse for a file.

Example:

clRFU myProgram.bin -fi myflash.ini

-pb PilotBiosPathName

Description:

Select a new secondary loader.

Default:

\bios\pilot.bin

RFU GUI Equivalent:

From the Setup | Boot Strap Loaders dialog box, type in a pathname or click on the ellipses radio button to browse for a file.

Example:

clRFU myProgram.bin -pb mySecondaryLoader.bin

-s port:baudrate

Description:

Select the comm port and baud rate for the serial connection.

Default:

COM1 and 115,200 bps

RFU GUI Equivalent:

From the Setup | Communications dialog box, choose values from the Baud Rate and Comm Port drop-down menus.

Example:

clRFU myProgram.bin -s 2:115200

-v

Description:

Causes the RFU version number and additional status information to be displayed.

Default:

Only error messages are displayed.

RFU GUI Equivalent:

Status information is displayed by default and there is no option to turn it off.

Example:

clRFU myProgram.bin -v

-vp+

Description:

Verify the presence of the processor by using the DSR line of the PC serial connection.

Default:

The processor is verified.

RFU GUI Equivalent:

From the “Communications Options” dialog box, visible by selecting Setup | Communications, check the “Enable Processor Detection” option.

Example:

clRFU myProgram.bin -vp+

-vp-

Description:

Do not verify the presence of the processor.

Default:

The processor is verified.

RFU GUI Equivalent:

From the “Communications Options” dialog box, visible by selecting
Setup | Communications, uncheck the “Enable Processor Detection” option.

Example:

clRFU myProgram.bin -vp-

-usb+

Description:

Enable use of USB to serial converter.

Default:

The use of the USB to serial converter is disabled.

RFU GUI Equivalent:

From the “Communications Options” dialog box, visible by selecting Setup | Communications, check the “Use USB to Serial Converter” option.

Example:

clRFU myProgram.bin -usb+

-usb-

Description:

Disable use of USB to serial converter.

Default:

The use of the USB to serial converter is disabled.

RFU GUI Equivalent:

From the “Communications Options” dialog box, visible by selecting Setup | Communications, uncheck the “Use USB to Serial Converter” option.

Example:

clRFU myProgram.bin -usb-