txt: ## dist_cpan-CTILMES-Native-Compile.md
  # 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.
  