Cleanup (#104)

* Reorganize main compilation functions, update docstrings and README

* Document and export `@device_overload`

* Typo

Author: brenhinkeller

README.md

@@ -15,7 +15,10 @@ using Pkg
 Pkg.add("StaticCompiler")
 ```
 
-There are two main ways to use this package. The first is via the `compile` function, which can be used when you want to compile a Julia function for later use from within Julia:
+There are two main ways to use this package:
+
+### Linked compilation
+The first option is via the `compile` function, which can be used when you want to compile a Julia function for later use from within Julia:
 ```julia
 julia> using StaticCompiler
 
@@ -43,7 +46,8 @@ julia> fib_compiled(10)
 ```
 See the file `tests/runtests.jl` for some examples of functions that work with `compile` (and some that don't, marked with `@test_skip`).
 
-The second way to use this package is via the `compile_executable` and `compile_shlib` functions, for use when you want to compile a Julia function to a native executable or shared library for use from outside of Julia:
+### Standalone compilation
+The second way to use this package is via the `compile_executable` and `compile_shlib` functions, for when you want to compile a Julia function to a native executable or shared library for use from outside of Julia:
 ```julia
 julia> using StaticCompiler, StaticTools
 
@@ -68,7 +72,7 @@ This package uses the [GPUCompiler package](https://github.com/JuliaGPU/GPUCompi
 ## Limitations
 
 * GC-tracked allocations and global variables do work with `compile`, but the way they are implemented is brittle and can be dangerous. Allocate with care.
-* GC-tracked allocations and global variables do *not* work with `compile_executable` (yet).
-* Type unstable code is not yet supported.
-* Doesn't currently work on Windows.
-* If you find any other limitations, let us know. There's probably lots.
+* GC-tracked allocations and global variables do *not* work with `compile_executable` or `compile_shlib`. This has some interesting consequences, including that all functions _within_ the function you want to compile must either be inlined or return only native types (otherwise Julia would have to allocate a place to put the results, which will fail).
+* Since error handling relies on libjulia, you can only throw errors from standalone-compiled (`compile_executable` / `compile_shlib`) code if an explicit overload has been defined for that particular error with `@device_override` (see [quirks.jl](src/quirks.jl)).
+* Type instability. Type unstable code cannot currently be statically compiled via this package.
+* Doesn't work on Windows. PRs welcome.

src/StaticCompiler.jl

@@ -13,6 +13,7 @@ using StaticTools: @symbolcall, @c_str, println
 
 export compile, load_function, compile_shlib, compile_executable
 export native_code_llvm, native_code_typed, native_llvm_module, native_code_native
+export @device_override, @print_and_throw
 
 include("target.jl")
 include("pointer_patching.jl")
@@ -173,7 +174,11 @@ end
 
 """
 ```julia
-compile_executable(f, types::Tuple, path::String, name::String=repr(f); filename::String=name, kwargs...)
+compile_executable(f::Function, types::Tuple, path::String, [name::String=repr(f)];
+    filename::String=name,
+    cflags=``, # Specify libraries you would like to link against, and other compiler options here
+    kwargs...
+)
 ```
 Attempt to compile a standalone executable that runs function `f` with a type signature given by the tuple of `types`.
 
@@ -207,7 +212,7 @@ julia> function print_args(argc::Int, argv::Ptr{Ptr{UInt8}})
        end
 
 julia> compile_executable(print_args, (Int, Ptr{Ptr{UInt8}}))
-"/Users/foo/code/StaticCompiler.jl/print_args"
+""/Users/user/print_args""
 
 shell> ./print_args 1 2 3 4 Five
 ./print_args
@@ -223,13 +228,16 @@ julia> using StaticTools # So you don't have to define `puts` and friends every
 julia> hello() = println(c"Hello, world!") # c"..." makes a stack-allocated StaticString
 
 julia> compile_executable(hello)
-"/Users/foo/code/StaticCompiler.jl/hello"
+"/Users/cbkeller/hello"
+
+shell> ls -alh hello
+-rwxr-xr-x  1 user  staff    33K Mar 20 21:11 hello
 
 shell> ./hello
 Hello, world!
 ```
 """
-function compile_executable(f, types=(), path::String="./", name=GPUCompiler.safe_name(repr(f));
+function compile_executable(f::Function, types=(), path::String="./", name=GPUCompiler.safe_name(repr(f));
         filename=name,
         cflags=``,
         kwargs...
@@ -244,9 +252,6 @@ function compile_executable(f, types=(), path::String="./", name=GPUCompiler.saf
     nativetype = isprimitivetype(rt) || isa(rt, Ptr)
     nativetype || @warn "Return type `$rt` of `$f$types` does not appear to be a native type. Consider returning only a single value of a native machine type (i.e., a single float, int/uint, bool, or pointer). \n\nIgnoring this warning may result in Undefined Behavior!"
 
-    # Would be nice to use a compiler pass or something to check if there are any heap allocations or references to globals
-    # Keep an eye on https://github.com/JuliaLang/julia/pull/43747 for this
-
     generate_executable(f, tt, path, name, filename; cflags=cflags, kwargs...)
 
     joinpath(abspath(path), filename)
@@ -255,11 +260,35 @@ end
 
 """
 ```julia
-compile_shlib(f, types::Tuple, path::String, name::String=repr(f); filename::String=name, kwargs...)
+compile_shlib(f::Function, types::Tuple, [path::String="./"], [name::String=repr(f)]; filename::String=name, cflags=``, kwargs...)
+compile_shlib(funcs::Array, [path::String="./"]; filename="libfoo", demangle=false, cflags=``, kwargs...)
 ```
 As `compile_executable`, but compiling to a standalone `.dylib`/`.so` shared library.
+
+### Examples
+```julia
+julia> using StaticCompiler, LoopVectorization
+
+julia> function test(n)
+                  r = 0.0
+                  @turbo for i=1:n
+                      r += log(sqrt(i))
+                  end
+                  return r/n
+              end
+test (generic function with 1 method)
+
+julia> compile_shlib(test, (Int,))
+"/Users/user/test.dylib"
+
+julia> test(100_000)
+5.2564961094956075
+
+julia> ccall(("julia_test", "test.dylib"), Float64, (Int64,), 100_000)
+5.2564961094956075
+```
 """
-function compile_shlib(f, types=(), path::String="./", name=GPUCompiler.safe_name(repr(f));
+function compile_shlib(f::Function, types=(), path::String="./", name=GPUCompiler.safe_name(repr(f));
         filename=name,
         cflags=``,
         kwargs...
@@ -273,28 +302,34 @@ function compile_shlib(f, types=(), path::String="./", name=GPUCompiler.safe_nam
     nativetype = isprimitivetype(rt) || isa(rt, Ptr)
     nativetype || @warn "Return type `$rt` of `$f$types` does not appear to be a native type. Consider returning only a single value of a native machine type (i.e., a single float, int/uint, bool, or pointer). \n\nIgnoring this warning may result in Undefined Behavior!"
 
-    # Would be nice to use a compiler pass or something to check if there are any heap allocations or references to globals
-    # Keep an eye on https://github.com/JuliaLang/julia/pull/43747 for this
     generate_shlib(f, tt, true, path, name, filename; cflags=cflags, kwargs...)
 
     joinpath(abspath(path), filename * "." * Libdl.dlext)
 end
+# As above, but taking an array of functions and returning a single shlib
+function compile_shlib(funcs::Array, path::String="./";
+        filename="libfoo",
+        demangle=false,
+        cflags=``,
+        kwargs...
+    )
+    for func in funcs
+        f, types = func
+        tt = Base.to_tuple_type(types)
+        isconcretetype(tt) || error("input type signature `$types` is not concrete")
 
-function generate_shlib_fptr(f, tt, path::String=tempname(), name = GPUCompiler.safe_name(repr(f)), filename::String=name;
-                            temp::Bool=true,
-                            kwargs...)
-
-    generate_shlib(f, tt, false, path, name; kwargs...)
-    lib_path = joinpath(abspath(path), "$filename.$(Libdl.dlext)")
-    ptr = Libdl.dlopen(lib_path, Libdl.RTLD_LOCAL)
-    fptr = Libdl.dlsym(ptr, "julia_$name")
-    @assert fptr != C_NULL
-    if temp
-        atexit(()->rm(path; recursive=true))
+        rt = last(only(native_code_typed(f, tt)))
+        isconcretetype(rt) || error("`$f$types` did not infer to a concrete type. Got `$rt`")
+        nativetype = isprimitivetype(rt) || isa(rt, Ptr)
+        nativetype || @warn "Return type `$rt` of `$f$types` does not appear to be a native type. Consider returning only a single value of a native machine type (i.e., a single float, int/uint, bool, or pointer). \n\nIgnoring this warning may result in Undefined Behavior!"
     end
-    fptr
+
+    generate_shlib(funcs, true, path, filename; demangle=demangle, cflags=cflags, kwargs...)
+
+    joinpath(abspath(path), filename * "." * Libdl.dlext)
 end
 
+
 """
 ```julia
 generate_shlib_fptr(path::String, name)
@@ -338,25 +373,40 @@ function generate_shlib_fptr(path::String, name, filename::String=name)
     @assert fptr != C_NULL
     fptr
 end
+# As above, but also compile (maybe remove this method in the future?)
+function generate_shlib_fptr(f, tt, path::String=tempname(), name = GPUCompiler.safe_name(repr(f)), filename::String=name;
+                            temp::Bool=true,
+                            kwargs...)
+
+    generate_shlib(f, tt, false, path, name; kwargs...)
+    lib_path = joinpath(abspath(path), "$filename.$(Libdl.dlext)")
+    ptr = Libdl.dlopen(lib_path, Libdl.RTLD_LOCAL)
+    fptr = Libdl.dlsym(ptr, "julia_$name")
+    @assert fptr != C_NULL
+    if temp
+        atexit(()->rm(path; recursive=true))
+    end
+    fptr
+end
 
 """
 ```julia
 generate_executable(f, tt, path::String, name, filename=string(name); kwargs...)
 ```
 Attempt to compile a standalone executable that runs `f`.
+Low-level interface; you should generally use `compile_executable` instead.
 
 ### Examples
 ```julia
-julia> function test(n)
-           r = 0.0
-           for i=1:n
-               r += log(sqrt(i))
-           end
-           return r/n
-       end
-test (generic function with 1 method)
+julia> using StaticCompiler, StaticTools
 
-julia> path, name = StaticCompiler.generate_executable(test, Tuple{Int64}, "./scratch")
+julia> hello() = println(c"Hello, world!")
+
+julia> path, name = StaticCompiler.generate_executable(hello, Tuple{}, "./")
+("./", "hello")
+
+shell> ./hello
+Hello, world!
 ```
 """
 function generate_executable(f, tt, path=tempname(), name=GPUCompiler.safe_name(repr(f)), filename=string(name);
@@ -404,36 +454,43 @@ end
 
 """
 ```julia
-generate_shlib(f, tt, path::String, name::String, filenamebase::String="obj"; kwargs...)
+generate_shlib(f::Function, tt, [external::Bool=true], [path::String], [name], [filename]; kwargs...)
+generate_shlib(funcs::Array, [external::Bool=true], [path::String], [filename::String]; demangle=false, kwargs...)
 ```
 Low level interface for compiling a shared object / dynamically loaded library
  (`.so` / `.dylib`) for function `f` given a tuple type `tt` characterizing
 the types of the arguments for which the function will be compiled.
-See also `StaticCompiler.generate_shlib_fptr`.
+
 ### Examples
 ```julia
+julia> using StaticCompiler, LoopVectorization
+
 julia> function test(n)
            r = 0.0
-           for i=1:n
+           @turbo for i=1:n
                r += log(sqrt(i))
            end
            return r/n
        end
 test (generic function with 1 method)
-julia> path, name = StaticCompiler.generate_shlib(test, Tuple{Int64}, "./test")
-("./test", "test")
+
+julia> path, name = StaticCompiler.generate_shlib(test, Tuple{Int64}, true, "./example")
+("./example", "test")
+
 shell> tree \$path
-./test
-|-- obj.o
-`-- obj.so
+./example
+|-- test.dylib
+`-- test.o
 0 directories, 2 files
+
 julia> test(100_000)
-5.256496109495593
-julia> ccall(StaticCompiler.generate_shlib_fptr(path, name), Float64, (Int64,), 100_000)
-5.256496109495593
+5.2564961094956075
+
+julia> ccall(("julia_test", "example/test.dylib"), Float64, (Int64,), 100_000)
+5.2564961094956075
 ```
 """
-function generate_shlib(f, tt, external = true, path=tempname(), name=GPUCompiler.safe_name(repr(f)), filename=name;
+function generate_shlib(f::Function, tt, external::Bool=true, path::String=tempname(), name=GPUCompiler.safe_name(repr(f)), filename=name;
         cflags=``,
         kwargs...
     )
@@ -455,6 +512,23 @@ function generate_shlib(f, tt, external = true, path=tempname(), name=GPUCompile
 
     path, name
 end
+# As above, but taking an array of functions and returning a single shlib
+function generate_shlib(funcs::Array, external::Bool=true, path::String=tempname(), filename::String="libfoo";
+        demangle=false,
+        cflags=``,
+        kwargs...
+    )
+
+    lib_path = joinpath(path, "$filename.$(Libdl.dlext)")
+
+    _,obj_path = generate_obj(funcs, external, path, filename; demangle=demangle, kwargs...)
+    # Pick a Clang
+    cc = Sys.isapple() ? `cc` : clang()
+    # Compile!
+    run(`$cc -shared $cflags $obj_path -o $lib_path `)
+
+    path, name
+end
 
 function native_code_llvm(@nospecialize(func), @nospecialize(types); kwargs...)
     job, kwargs = native_job(func, types, true; kwargs...)
@@ -524,46 +598,4 @@ function generate_obj(funcs::Array, external, path::String = tempname(), filenam
     path, obj_path
 end
 
-function generate_shlib(funcs::Array, external = true, path::String = tempname(), filename::String="libfoo";
-        demangle=false,
-        cflags=``,
-        kwargs...
-    )
-
-    lib_path = joinpath(path, "$filename.$(Libdl.dlext)")
-
-    _,obj_path = generate_obj(funcs, external, path, filename; demangle=demangle, kwargs...)
-    # Pick a Clang
-    cc = Sys.isapple() ? `cc` : clang()
-    # Compile!
-    run(`$cc -shared $cflags $obj_path -o $lib_path `)
-
-    path, name
-end
-
-function compile_shlib(funcs::Array, path::String="./";
-    filename="libfoo",
-    demangle=false,
-    cflags=``,
-    kwargs...)
-    for func in funcs
-        f, types = func
-        tt = Base.to_tuple_type(types)
-        isconcretetype(tt) || error("input type signature `$types` is not concrete")
-
-        rt = last(only(native_code_typed(f, tt)))
-        isconcretetype(rt) || error("`$f$types` did not infer to a concrete type. Got `$rt`")
-        nativetype = isprimitivetype(rt) || isa(rt, Ptr)
-        nativetype || @warn "Return type `$rt` of `$f$types` does not appear to be a native type. Consider returning only a single value of a native machine type (i.e., a single float, int/uint, bool, or pointer). \n\nIgnoring this warning may result in Undefined Behavior!"
-    end
-
-# Would be nice to use a compiler pass or something to check if there are any heap allocations or references to globals
-# Keep an eye on https://github.com/JuliaLang/julia/pull/43747 for this
-
-    generate_shlib(funcs, true, path, filename; demangle=demangle, cflags=cflags, kwargs...)
-
-    joinpath(abspath(path), filename * "." * Libdl.dlext)
-end
-
-
 end # module

src/target.jl

@@ -6,7 +6,18 @@ end
 
 const overrides = quote end
 
-
+"""
+```julia
+@device_override old_bad_method(arg1::Type1, arg2::Type2) = new_good_method(arg1, arg2)
+```
+Override a non-static-compilable method (e.g. `old_bad_method(::Type1, ::Type2)`)
+with a more compileable replacement.
+### Examples
+```
+@device_override @noinline Core.throw_inexacterror(f::Symbol, ::Type{T}, val) where {T} =
+    @print_and_throw c"Inexact conversion"
+```
+"""
 macro device_override(ex)
     ex = macroexpand(__module__, ex)
     if Meta.isexpr(ex, :call)
@@ -24,7 +35,6 @@ macro device_override(ex)
     end
 end
 
-
 Base.@kwdef struct NativeCompilerTarget <: GPUCompiler.AbstractCompilerTarget
     cpu::String=(LLVM.version() < v"8") ? "" : unsafe_string(LLVM.API.LLVMGetHostCPUName())
     features::String=(LLVM.version() < v"8") ? "" : unsafe_string(LLVM.API.LLVMGetHostCPUFeatures())