=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<BuildToolchainRepo::Lang::CRepo::get-toolchain()>.
To directly use a specific compiler, just instanciate a C<BuildToolchainRepo::Lang::C::Something>
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<method compile($c-file, $o-file --> Int>
Compile a single C file to an O file. Returns the compiler exit code.
=end item
=begin item
C<method link-lib-shared(@o-files, $out-path, $lib-name --> 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<method link-executable(@o-files, $out-path, $exe-name --> 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<method is-available(--> 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<BuildToolchainRepo::Lang::CProbeHelpers> provides two subs:
=item C<sub probe-exitcode(Str $code, BuildToolchainRepo::Lang::C $t --> Int)>
=item C<sub probe-compile-exitcode(Str $code, BuildToolchainRepo::Lang::C $t --> 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<BuildToolchainRepo::Lang::CProbeResult>.
Probes can then be added to toolchains via C<$t.probes.push: your-probe()>.
This causes a respective preprocessor define C<HAS_YOUR_NAME> 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<gcc> executable.
=AUTHOR Patrick Böker <patrick.boeker@posteo.de>
=head1 License
This module is distributed under the terms of the Artistic License 2.0.
=end pod