crun

= Crun

• Introduction
• Example runs
• Options
• Issues

= Introduction

Crun is an utility for compiling and running C-programs straight from C source files. Crun supports compile-run and compile-debug flows.

User can embed custom compile options into the main c-file, if user need, for example, an external library for the program. User can also control the command line parameters passed to the program through Crun.

Crun is usually used with one c-file, i.e. the main file. However program can be split into multiple files, but main has to be first in the list of files. Crun is targeted for small C-programs, so it is not typical to have multiple files.

User of Crun is most probably trying out some basic C-features or maybe prototyping with some algorithm.

User can avoid listing stardard POSIX headers, if the Autoheader mode is used. Autoheader mode will silently add "#include" directives to the start of source files for user.

In Autoheader mode, the source files are examined for function calls. The function calls that are part of POSIX, will get the corresponding header files automatically included. Other libraries (and includes) are not handled, since the possibility for ambiguous function names are too high. Autoheader mode is activated with "-a" option. Before Autoheader mode is used, user should update the Autoheader DB:

shell> auto -u

= Example runs

In order to run "Hello World" example with Crun, user need to have the C source file with "Hello World" program in it. This is available in the "examples" directory for user.

"hello.c" content:

#include <stdio.h> int main( int argc, char** argv ) { printf( "Hello World!\n" ); return 0; }

User can execute compile-run flow by:

shell> crun -f examples/hello.c

The output from program is:

Hello World!

User can execute compile-debug flow by:

shell> crun -f examples/hello.c -d

Program is compiled and gdb is started so that the program stops at "main" (i.e. default behavior).

Check available command line interface, CLI, options for Crun:

shell> crun -h

= Options

User can specify options for Crun in multiple ways. Typically CLI is used to control Crun, but if the program uses static compilation options, those live most naturally in the source file itself.

Options are stored to a hash called "@crun". Each option name is a key in the hash, and the option values are Arrays.

For example the entry:

@crun['progopts']

specify the command line parameters given to the program compiled and run by Crun.

Here is the complete list of options that control Crun:

[ compopts ]

Array of user's compilation options. E.g. "-l lm" to include the math lib. Default is: [].

[ progopts ]

Array of command line parameters for the program run. E.g. ["-c 12"]. Default is: [].

[ stopopts ]

Array of breakpoints for the debugger. E.g. ["add"] defines that the debugger stops at "add" function. Default is: ["main"].

[ compprog ]

Array including the compiler name and base options. This options array should only have one entry, but in theory user could have multiple entries. The entries are concatenated with SPACE. The compiler command has to have same command line parameters as "gcc". Default is: ["gcc", "-Wall", "-std=c11"].

[ dbugprog ]

Array including the debugger name and base options. This options array should only have one entry, but in theory user could have multiple entries. The entries are concatenated with SPACE. The debugger command has to have same command line parameters as "gdb". Default is: ["gdb", "--nx"].

[ crunopts ]

Array of compiler options managed by Crun. User don't have to control this option. Default is: [].

Crun sets Options to default values and then applies the user overrides from various sources, given below.

User can embed the options to the C source file. This is the recommended way because this way the settings will follow the code. Additional compilation options and CLI options for the compiled program would be given as:

/*

• Options for crun:
• -crun-compopts:=-O2
• crun-compopts:+-lm
• crun-compopts:.-std=c99
• crun-progopts:=-c 12 */

The syntax is "crun-". If there is no space before "crun", the setting is not used, i.e. first "compopts" is neglected above.

User can specify static overrides in "$HOME/.crun" file and/or in "./.crun". In addition to these predefined files, user can use the "-c" Crun CLI option to read in option overrides.

For example if the program is always run with "-c 10" command line options, user can set in ".crun":

@crun['progopts'] = [ "-c 10" ]

An alternative way to achieve the same thing is to use Crun CLI and use the -o option:

shell> crun -o "progopts:=-c 10" ...

This sets the list of program options to "-c 10". ":=" syntax means setting the Array of options. If user needs to add to existing list of options, perform:

shell> crun -o "progopts:+-c 10" ...

Thus ":+" is the syntax for appending more options to existing list.

If user wants to put an option to start of list, the ":." syntax is used.

The simplest way to pass 'progopts' to target program is using the "-p" CLI option. However user must be aware of the shell option parsing, since it is very easy to miss the target program and actually pass the option to Crun.

If user wants to pass '-' based option to target program:

shell> crun -p "-c 10" ...

The backslash before "-c" will ensure that "-c" does not become an option for Crun.

Summary of option setting from first to last:

• Defaults (from crun program).
• ".crun" from home directory.
• ".crun" from current directory.
• Options embedded to C source file (main file).
• "-c" options from files.
• "-o" options from Crun CLI.
• "-p" options for program (only).

The options are applied in this order, and later options may override the earlier settings, i.e. CLI options have the highest priority.

= Issues

If user takes C source input from STDIN, debug option can't be used. Only compile-run flow is possible.