# Native::Compile - Native Compiling for Raku Modules

# SYNOPSIS

    # META6.json
    "resources" : [ "libraries/mylib" ]

    # MyModule.rakumod
    my constant LIB = %?RESOURCES<libraries/mylib>;
    sub myfunc() is native(LIB) {}

    # A Simple Build.rakumod example:
    use Native::Compile;
    class Build {
      method build($dir) {
          build :$dir, :lib<mylib>, :src<src/myfile.c>
      }
    }

    # More explicit separate steps Build.rakumod:
    use Native::Compile;
    class Build {
        method build($dir) {
            indir $dir, {
                my $obj = compile('src/myfile.c');
                link('mylib', @$obj);
            }
        }
    }

    # A more complicated Build.rakumod:
    use Native::Compile;
    class Build {
      method build($dir, :$verbose, :$dryrun) {
          build :$dir, :lib<mylib>, :src<src/myfile.c>, :cc<clang>,
          :extra-cflags<-O>, :$verbose, :$dryrun, :clean,
          fallback => [ %( :os<windows>              # special name for windows
                           :url<http://somewhere/mylib.dll>,
                           :hash<abcd343534...> ),   # SHA256
                        %( :os<darwin>,
                           :version(v10.14+),        # Version comparisons
                           :url<http://somewhere/mylib.dylib>,
                           :hash<abcd343534...> ) ]
      }
    }

# DESCRIPTION

Compile C and C++ sources, linking them into a shared library in the
module resources.  If a prebuilt library is available for Windows or
Mac OS/X, it can download it if a compiler is not available.

This module also exports a `MAIN` subroutine so you can make your
`Build.rakumod` executable and things will just work.  It takes the
*-v* / *--verbose* and *-n* / *--dryrun* flags and passes them on to
the `Build.build()`, which can be useful for debugging the build
process.

It exports a number of subroutines that capture what I've observed as
frequent boilerplate for doing this sort of thing throughout the
ecosystem.  Many examples seem to do it slightly differently, and I'm
not sure this is yet optimal.  This is still a work in progress, and
the interface may still change.  I'd like to support the most common
cases here, making easy things easy.  Hopefully the **build**
subroutine is all you really need, though the other functions are
exposed if they are useful.  You can manually perform the compile/link
steps in class `Build` if needed.

This module is modelled after, and draws from LibraryMake. It doesn't have
the full capabilities of LibraryMake, but for very simple and common cases,
it reduces the amount of required boilerplate. If you need more complex
capabilities, just write a full Makefile and use LibraryMake.

That said, if there is a capability you think would fit into this module,
please propose, either an idea, or even a patch.

# SUBROUTINES

### sub get-vars(*%args)

Get various compiling variables ala LibraryMake Many of the variables
are retrieved from the VM, based on the original system
compilation. Some are overridden by more appropriate choice. Each of
the variables can also be overridden by named parameters passed in to
this routine, and finally by Environment variables.

### sub win-hash($path, :$verbose, :$dryrun)

Use Windows powershell to compute a sha256 hash of a file

### sub win-fetch($url, $file, :$verbose, :$dryrun)

Use Windows powershell to download a file from a url

### sub openssl-hash($path, :$verbose, :$dryrun)

Use openssl to compute a sha256 hash

### sub curl-fetch($url, $file, :$verbose, :$dryrun)

Use curl to download a file from a url

### sub compile($src, :$obj, *%args)

Compile a single source file with the right compiler.  Can override
defaults with params :cc, :cxx, :cflags, :cxxflags, :extra-cxxflags,
:ccswitch, :ccout or the usual :verbose or :dryrun. Returns the path
to the compiled object.

### sub link($lib, @obj, :$dir = "resources/libraries", :$cpp, *%args)

Link objects into a shared library, defaulting to the
`resources/libraries` directory. The library name is mangled to match
the system (e.g. `.so`, `.dylib`, `.dll`). Set the :cpp flag to foce
use of the C++ to link so symbols will work right. Can override
defaults with params :cxxld, :ld, :ldflags, :extra-ldflags, :ldshared,
:ldout or the usual :verbose or :dryrun

### sub fetch( :$lib, :$url, :$hash, :$dir = "resources/libraries", *%args)

Fetch a library from a URL, name mangle the library and install into
resources/libraries by default, pass in :verbose or :dryrun as usual

### sub fallback($lib, @fallback, *%args)

Process a list of fallback library fetching alternatives, each
possibly with an os/version, a url for the library, and a sha256 hash
for the library.

### sub build(:$lib, :@src, :@fallback, :$clean, :$dir, *%args)

Build a library from sources in directory :dir compile each source
file, then link. Pass in :clean to remove objects after linking. Other
named parameters passed in are forwarded to the
compiler/linker. Additionally a fallback list will be processed on any
error if present.

### sub MAIN(Str :$dir = ".", Bool :n(:$dryrun), Bool :v(:$verbose))

For command line building

# LICENSE

This work is subject to the Artistic License 2.0.