=begin pod
=NAME BuildToolchainRepo
A repository of compiler build toolchains
=head1 Synopsis
use BuildToolchainRepo::Lang::CRepo;
my $c-file = "hello.c";
my $o-file = "hello.o";
my $e-name = "hello";
my $t = BuildToolchainRepo::Lang::CRepo::get-toolchain().new;
my $cexit = $t.compile($c-file, $o-file);
my ($lexit, $e-file) = $t.link-executable(@$o-file, $dir, $e-name);
my $p = run $e-file;
=head1 Description
This module aims to provide a lightweight interface to build toolchains or in
other words: provide an easy way to build your C (or some other lang) code.
=head1 Compiling
Compilers can be searched automatically via C.
To directly use a specific compiler, just instanciate a C
class directly.
Such C toolchain objects provide a set of variables to modify their behavior
and a few methods to do the actual compiling.
=begin item
C Int>
Compile a single C file to an O file. Returns the compiler exit code.
=end item
=begin item
C List>
Link one or more O files to a shared object file. C<$out-path> is the folder
where the library should be placed in. C<$lib-name> is the name (not filename)
of the library.
Returns a list with two elements: The exit code of the compiler and a full path
of the generated library. The filename will differ from the given name, as it
will have the platform specific prefix and suffix added.
=end item
=begin item
C List)>
Link one or more O files to a shared object file. C<$out-path> is the folder
where the library should be placed in. C<$lib-name> is the name (not filename)
of the library.
Returns a list with two elements: The exit code of the compiler and a full path
of the generated library. The filename will differ from the given name, as it
will have the platform specific prefix and suffix added.
=end item
=begin item
C Bool)>
Is the toolchain at hand is available on the system?
=end item
=head1 Probes
Some tooling is provided, to simplify working with feature probes.
C provides two subs:
=item C Int)>
=item C Int)>
Both take a piece of C code and a toolchain and return the exit code of the
program or compiler respectively.
To write a probe, implement a function returning an object of type C.
Probes can then be added to toolchains via C<$t.probes.push: your-probe()>.
This causes a respective preprocessor define C with value 1 to
be set for all successful probes;
=head1 Environment Variables
=head2 C_TOOLCHAIN
Set this to the name of a C toolchain, to force using that specific toolchain.
=head GCC_PATH
When using the GCC toolchain, sets the path to look for the C executable.
=AUTHOR Patrick Böker
=head1 License
This module is distributed under the terms of the Artistic License 2.0.
=end pod