== 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[[BR]]
   b) \its\fullPath\assemblyFileName.exe or \its\fullPath\assemblyFileName.dll[[BR]]


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



TODO Sections
    * Files:file
    * Controlling type of executable built -target/-t
    * Providing references and library search path -reference/-ref -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:

 * [http://cobra-language.com/forums/viewtopic.php?f=4&t=194 discussion: multiple files]
 * [http://cobra-language.com/forums/viewtopic.php?f=4&t=197 discussion: Importing Cobra Files]

See also: MsxBuild, LanguageTopics, LibraryTopics