Cobra Compiler Command Line

Quick examples:

  # compile and run immediately (if no errors)
cobra myprog.cobra

  # get help
cobra -h

  # compile only
cobra -c myprog.cobra

  # with debug
cobra -d -c myprog.cobra

  # multiple source files
cobra -c foo.cobra bar.cobra

  # passing arguments
cobra foo.cobra bar.cobra -- arg1 arg2

  
  # disable all checks, contracts, asserts, etc.
  # maximum performance
cobra -turbo foo.cobra

Getting help:

cobra -h
cobra -help

will dump a page detailing all the command line options supported.

The compiler runs for each invocation in a particular mode of operation. These correspond to the 'commands on paths'

• -compile or -c - compile the provided files and bind into an executable
• -run-exe or -r - as for -compile but run the executable after successful compilation. This is the default mode if none other is given
• -test - as for -compile but run the executables test cases after successful execution
• -document - parse the provided files and generate documentation from the parse tree

In addition there are three standalone commands

• -help or -h - display the cobra commandline options and descriptions
• -about - display info about cobra
• -version - display the cobra executables version information

Commandline items that are not options ( begin with '-') are taken to be filenames. Cobra can take one or a list of commandline given files to compile and the files can be cobra code ( filename ends in '.cobra') or C# code ( filename ends in '.cs'). Filenames without any extension are assumed to be a cobra code file of the same name with a '.cobra' extension

i.e

cobra myProg.cobra 
cobra myProg

both do the same thing - compile a cobra code file myProg.cobra to an executable and run it (if compilation succeeds)

Options

options form : -[option or synonym]:value

-reference/-ref

• Specifies a file (in .Net an assembly file) that can resolve 'using namespace' references.

Providing a reference to a resolving file is done using -ref: option file and can specify an absolute pathname or a filename.

• in .Net this can can be either an .exe or a .dll .

a) assemblyFileName.exe or assemblyFileName.dll
b) \its\fullPath\assemblyFileName.exe or \its\fullPath\assemblyFileName.dll

e.g.
cobra -c -ref:anyAssembly.dll codeFile.cobra
                 or 
cobra -c -ref:anyAssembly.exe codeFile.cobra

#with Full Paths
cobra -c -ref:\its\fullPath\anyValidAssembly.dll codeFile.cobra
                 or 
cobra -c -ref:\its\fullPath\anyValidAssembly.exe codeFile.cobra

If you are not providing the paths of the referenced assemblies then you can use
the -lib: option to give additional paths for the compiler to search for the referenced assemblies.
This can work well for assemblies outside of the GAC i.e private assemblies
but if you want to include (something like) System.Speech which is found in both .net 3.5
and .net 4.0 even if you specify additional paths to search using -lib:,
if the compiler is compiled on .net 4.0 it may default to using the .net 4.0 version.
So when you need to unambiguously specify paths to the referenced assembly use an absolute pathname
i.e use -ref:\withFullPath\to\requiredAssembly.dll or .exe

-files:filename

Specify a filename containing a list of files to compile.

Files are specified one sourcefile name per line and lines may be space separated. Lines containing a leading '#' are ignored as comment or documentary information

Source filenames should be given as specified on the command line ( filenames,partial or absolute pathnames with or without an explicit '.cobra' suffix').

This option is an accumulator so multiple occurrences will specify multiple files whoose contents will aggregate together.

e.g. Given a file named srcFiles containing

#srcFiles: cobra source files for ...

main.cobra
input

#Useful utilities local to this project
utils.cobra

the following compilation line

cobra -c -files:srcFiles

is exactly the same as

cobra -c main.cobra input utils.cobra
# which is the same as 
#cobra -c main.cobra input.cobra utils.cobra

This is useful compiling an executable with a large number of or non trivial hierarchy of source files.

-target/-t

Specifies the types of executable built where such needs specifying explicitly (.Net).

Current examples include: executable, GUI executable, Library.

Defaults to 'normal' executable

Values of this option can be a choice of one of :

• exe - build a normal executable
• winexe - build a windows executable ( .Net)
  • Program is assumed to be a GUI program providing its own windows.
  • Suppresses creation of a console window if not run from a console.
• lib - build a Library file (a .dll on .Net)
• module - build a module

e.g.
cobra -c codeFile.cobra
# build/compile a standard executable from cobra source in codeFile.cobra

cobra -c -t:exe codeFile.cobra
# same as above 

cobra -c -t:winexe  codeFile.cobra
# compile a windows(GUI) executable from cobra source in codeFile.cobra

cobra -c -t:lib codeFile.cobra
# build/compile a library file (dll) from cobra source in codeFile.cobra
# this is intended to be used as the target of a -ref option

TODO Sections

• Providing references and library search path -library-directory/-lib -embed-run-time/-ert
• Controlling compilation -include-{asserts, nil-checks, tests}
  • -optimize/-o -debug/-d -turbo/-t
  • -keep-intermediate-files/-kif
  • -contracts -verbosity/-v
• Specifying executable and args for it -run-args/-- and -run
• Error handling -detailed-stack-trace/dst -debugging-tips -exception-report -reveal-internal-exceptions
• Development cycle - colorize -editor
• Back end -sharp-compiler -sharp-args

Examples

Working with Multiple Files

For now, see:

•  discussion: multiple files
•  discussion: Importing Cobra Files

See also: MsxBuild, LanguageTopics, LibraryTopics