OBNC(1)                     General Commands Manual                    OBNC(1)

NAME
       obnc - build an executable for an Oberon module

SYNOPSIS
       obnc [-o OUTFILE] [-v | -V] [-x] INFILE
       obnc (-h | -v)

DESCRIPTION
       obnc  builds an executable file for an Oberon module. Before the module
       is compiled, object files for imported modules are recursively  created
       or updated as needed. Oberon modules are first compiled to C with obnc-
       compile.  Each C file is then compiled to object code with an  external
       C  compiler.  Finally,  the  object files are linked into an executable
       program. Oberon source filenames are expected to end with .obn, .Mod or
       .mod.   All  output files except the final executable are stored in the
       subdirectory .obnc.

       If for any module M there exists a file named M.c in the same directory
       as  the  Oberon source file then M.c will be used as the input to the C
       compiler instead of the generated  file  .obnc/M.c.   This  provides  a
       mechanism to implement a module in C.

       For  any module M, environment variables for the C compiler specific to
       M and environment variables for the linker can be  defined  in  a  file
       named M.env, located in the same directory as the Oberon source file.

OPTIONS
       -h     Display help and exit.

       -o OUTFILE
              Use pathname OUTFILE for the generated executable file.

       -v     Without  argument,  display  version and exit. Otherwise, output
              progress of compiled modules.

       -V     Output progress of compiled modules  with  compiler  and  linker
              subcommands.

       -x     Compile  and link modules from C source (if available) in a sin-
              gle command. When a program is cross-compiled, this option  pre-
              vents  using  object files compiled for the host system. It also
              prevents leaving behind object files which are incompatible with
              the host system.

ENVIRONMENT
       CC     Specifies the C compiler to use (default is cc).

       CFLAGS Options  for the C compiler. The following constants can be cus-
              tomized with the flag -D name=value and are intended to be  used
              with the option -x:

              OBNC_CONFIG_C_INT_TYPE
                     Controls  the  size of type INTEGER and SET. The value is
                     OBNC_CONFIG_SHORT, OBNC_CONFIG_INT,  OBNC_CONFIG_LONG  or
                     OBNC_CONFIG_LONG_LONG.

              OBNC_CONFIG_C_REAL_TYPE
                     Controls  the  size  of type REAL. The value is OBNC_CON-
                     FIG_FLOAT, OBNC_CONFIG_DOUBLE or OBNC_CONFIG_LONG_DOUBLE.

              OBNC_CONFIG_NO_GC
                     Value 1 builds an executable without the garbage  collec-
                     tor.  Calls to NEW invokes the standard memory allocation
                     functions in C instead. This option can be  used  if  the
                     program  does not use dynamic memory allocation or if the
                     total size of the allocated memory is bounded.

              OBNC_CONFIG_TARGET_EMB
                     Value 1 builds an executable for a freestanding execution
                     environment  (embedded  platform). With this option the C
                     main function takes no parameters. The garbage  collector
                     is  disabled and any call to NEW is invalidated. The exe-
                     cutable is not linked with the math library libm.

       LDFLAGS
              Additional options for the linker.

       LDLIBS Additional libraries to link with.

       OBNC_IMPORT_PATH
              See obnc-path(1)

EXAMPLES
   Getting Started
       In Oberon, the program to print "hello, world" is

              MODULE hello;

                     IMPORT Out;

              BEGIN
                     Out.String("hello, world");
                     Out.Ln
              END hello.

       Save the above module in a file named hello.obn and compile it with the
       command

              obnc hello.obn

       This  will  create  an executable file named hello.  When you run hello
       with the command

              ./hello

       it should print

              hello, world

   Interfacing to C
       To implement a module M in C:

       1. Create a file named M.obn with the the exported declarations

       2. Create a file named MTest.obn which imports M (and preferably  write
          unit tests for M)

       3. Build MTest with the command

              obnc MTest.obn

       4. Copy  the generated file .obnc/M.c to the current directory. In M.c,
          delete the generator comment on the first line and change  the  path
          in the include directive from M.h to .obnc/M.h.

       5. Implement M.c.

       Note:  The initialization function M__Init is called each time a client
       module imports M. Its statements should therefore be  guarded  with  an
       initialization flag to make sure they are executed only once.

AUTHOR
       Written by Karl Landstrom

SEE ALSO
       obnc-compile(1), obnc-path(1)

                                                                       OBNC(1)