The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
conjury-1.004
River stage zero No dependents
1 ++
/ Conjury::C

NAME

Conjury::C - Perl Conjury with C/C++ compilers, linkers and archivers

SYNOPSIS

  c_object
    Source => I<source-file>,
    Directory => I<directory>,
    Includes => [ I<dir1>, I<dir2>, ... ],
    Defines => { I<var1> => I<val1>, I<var2> => I<val2>, ... },
    Compiler => I<compiler>,
    Options => [ I<opt1>, I<opt2>, ... ],
    Factors => [ I<factor1>, I<factor2>, ... ];

  c_executable
    Directory => I<directory>,
    Name => I<output-filename>,
    Order => [
    Searches => [ I<dir1>, I<dir2>, ... ],
    Objects => [ I<obj1>, I<obj2>, ... ],
    Libraries => [ I<lib1>, I<lib2>, ...] ],
    Linker => I<linker>,
    Options => [ I<opt1>, I<opt2>, ... ],
    Factors => [ I<factor1>, I<factors2>, ... ]

  c_static_library
    Directory => I<directory>,
    Name => I<output-filename>,
    Objects => [ I<obj1>, I<obj2>, ...],
    Archiver => I<archiver>,
    Options => [ I<opt1>, I<opt2>, ... ],
    Factors => [ I<factor1>, I<factors2>, ... ]

  c_compiler
    Program => I<program>,
    Options => [ I<opt1>, I<opt2>, ... ],
    Journal => I<journal>,
    Flag_Map => { 'I' => I<include-flag>, 'D' => I<define-flag>,
              'c' => I<source-flag>, 'o' => I<object-flag> },
    Suffix_Rule => sub { my ($name) = @_; ... return $result },
    Scanner => sub { my ($c_file, $args) = @_; ... return @result };

  c_compiler Vendor => I<vendor>, ...

  c_linker
    Program => I<program>,
    Options => [ I<opt1>, I<opt2>, ... ],
    Journal => I<journal>,
    Flag_Map => { 'l' => I<link-flag>, 'L' => I<search-flag>,
              'o' => I<output-flag> },
    Bind_Rule => sub { my ($lib, $bind) = @_;
                   ... return @result },
    Search_Rule => sub { my ($lib, $rule, $bind, @search) = @_;
                     ... return @factors };

  c_linker Vendor => I<vendor>, ...

  c_archiver
    Program => I<program>,
    Options => [ I<opt1>, I<opt2>, ... ],
    Journal => I<journal>,
    Flag_Map => { 'r' => I<replace-flag> };

  c_archiver Vendor => I<vendor>, ...

DESCRIPTION

Spells for compiling and linking C/C++ software are constructed using c_object, c_executable and c_static_library. The compiler, linker and archiver used in the resulting actions are the same compiler, linker and archiver that were used to build Perl itself, unless otherwise specified.

Specializations of the general classes of compiler, linker and archiver can be created using c_compiler, c_linker and c_archiver.

Compiling Objects From C/C++ Source

Use the c_object function to create a spell for compiling an object file from a C or C++ source file. The name of the resulting object file will be derived by removing the .c suffix and replacing it with the suffix for object files on the current platform.

Use the c_compiler function to create an object to represent a specialization of the C/C++ compiler tool class.

c_object

This function returns a spell for the action to compile a source file into an object file.

The 'Source' argument is required and specifies the name of the source file to compile into an object file.

The optional 'Directory' argument specifies the directory in which the object file should be produced.

The optional 'Includes' argument specifies a list of directories that should be used by the compiler to search for header files.

Preprocessor variables may be specified with the optional 'Defines' argument by placing the names of variables to set into the keys of a hash, and defining the values as needed.

The optional 'Compiler' argument specifies that a particular specialization of the C/C++ compiler tool be used (instead of the default compiler).

The optional 'Options' argument specifies a list of options with which to invoke the compiler for this particular object file.

The optional 'Factors' argument specifies additional factors to associate with the spell created.

c_compiler

This function returns an object representing a specialization of the C/C++ compiler class. If the 'Vendor' argument is specified, then the vendor-specific subclass of the Conjury::C::Compiler class parse the argument list. Otherwise, the specialization is applied to the base class used for the default compiler.

The optional 'Program' argument specifies the name of the program to invoke the compiler.

The optional 'Options' argument specifies the list of options with which the compiler should be invoked for all object files.

The optional 'Journal' argument specifies the journal object that should be used in creating all spells.

The optional 'Flag_Map' argument specifies a hash that sets the flag character for various standard options to C/C++ compilers for setting the include path, the preprocessor definitions, the source file and the output file.

The optional 'Suffix_Rule' argument specifies a subroutine that converts the name of a source file into the corresponding object file.

The optional 'Scanner' argument specifies a subroutine that finds the list of files that a source file references with '#include' directives.

Linking Executables From Objects

Use the c_executable function to create a spell for linking an executable program from a list of object files.

Use the c_linker function to create an object to represent a specialization of the C/C++ linker tool class.

c_executable

This function returns a spell for the action to link a list of object files and libraries into an executable file.

The optional 'Directory' argument specifies the directory where the executable program is to be produced. If unspecified, the directory of the current context is used.

The 'Name' argument is required and specifies the name of the executable program. Any filename extensions the system requires for executable program files will be appended automatically.

The 'Order' argument is a required list of verb-object pairs corresponding to orders for the linker to use in producing the executable. The 'Searches' verb specifies a list of directories to add to the library search path; the 'Objects' verb specifies a list of object files to link (either the spells that produce them, or the names of spells that will produce them); the 'Libraries' verb specifies the list of libraries to link. Order verbs may be specified in whatever sequence makes sense to the linker.

The optional 'Linker' argument specifies that a particular specialization of the C/C++ linker tool be used (instead of the default linker).

The optional 'Options' argument specifies a list of options with which to invoke the linker for this particular object file.

The optional 'Factors' argument specifies additional factors to associate with the spell created.

c_linker

This function returns an object representing a specialization of the C/C++ linker class. If the 'Vendor' argument is specified, then the vendor-specific subclass of the Conjury::C::Linker class parse the argument list. Otherwise, the specialization is applied to the base class used for the default linker.

The optional 'Program' argument specifies the name of the program to invoke the linker.

The optional 'Options' argument specifies the list of options with which the linker should be invoked for all product files.

The optional 'Journal' argument specifies the journal object that should be used in creating all spells.

The optional 'Flag_Map' argument specifies a hash that sets the flag character for various standard options to C/C++ linkers for setting the search path, the output file and the libraries to link.

The optional 'Bind_Rule' argument specifies a subroutine that takes a library name and a binding specification and returns a list of library filenames for which the binding specification applies. Typical binding specifications include 'static' and 'dynamic'-- and the unnamed specification, which typically implies "either dynamic or static as required."

The optional 'Search_Rule' argument specifies a subroutine that takes a library name, a binding rule (see above), a binding specification (also, see above), and a list of the current directories in the library search path (at the current point in the sequence of orders), and returns the list of factors which produce the library files.

Creating Static Archives Of Objects

Use the c_static_library function to create a spell for composing a static library from a list of object files.

Use the c_archiver function to create an object to represent a specialization of the C/C++ archiver tool class.

c_static_library

This function returns a spell for the action to archive a list of object files in a static library file.

The optional 'Directory' argument specifies the directory where the static library file is to be produced. If unspecified, the directory of the current context is used.

The 'Name' argument is required and specifies the name of the library file. Any filename extensions and prefixes the system requires for static library files will be added automatically.

The 'Objects' argument is required and specifies the list of objects (and/or spells that produce the objects) to be archived into the static library file.

The optional 'Archiver' argument specifies that a particular specialization of the C/C++ archiver tool be used (instead of the default archiver).

The optional 'Options' argument specifies a list of options with which to invoke the archiver for this particular object file.

The optional 'Factors' argument specifies additional factors to associate with the spell created.

c_archiver

This function returns an object representing a specialization of the C/C++ archiver class. If the 'Vendor' argument is specified, then the vendor-specific subclass of the Conjury::C::Archiver class parse the argument list. Otherwise, the specialization is applied to the base class used for the default archiver.

The optional 'Program' argument specifies the name of the program to invoke the archiver.

The optional 'Options' argument specifies the list of options with which the archiver should be invoked for all static library files.

The optional 'Journal' argument specifies the journal object that should be used in creating all spells.

The optional 'Flag_Map' argument specifies a hash that sets the flag character for various standard options to C/C++ archivers, including the flag for replacing existing objects with new ones.

SEE ALSO

The introduction to Perl Conjury is in Conjury. Other useful documents include cast and Conjury::Core.

The specialization for the GNU tools is documented in Conjury::C::GNU.

AUTHOR

James Woodyatt <jhw@wetware.com>