Merge pull request #2140 from Kaiepi/nativecall

More documentation on library paths and names
This closes #1513

Author: JJ

doc/Language/nativecall.pod6

@@ -659,18 +659,27 @@ to callbacks.
 
 =head1 Library Paths and Names
 
-=comment TODO
-
-TBD more
-
-The C<native> trait accepts the library name or the full path.
+The C<native> trait accepts the library name, the full path, or a subroutine
+returning either of the two. When using the library name, the name is assumed
+to be prepended with "lib" and appended with ".so" (or just appended with
+".dll" on Windows), and will be searched for in the paths in the
+LD_LIBRARY_PATH (PATH on Windows) environment variable.
 
+=begin code :skip-test
     use NativeCall;
     constant LIBMYSQL = 'mysqlclient';
     constant LIBFOO = '/usr/lib/libfoo.so.1';
+    sub LIBBAR {
+        my $path = qx/pkg-config --libs libbar/.chomp;
+        $path ~~ s/\/[[\w+]+ % \/]/\0\/bar/;
+        $path
+    }
     # and later
+
     sub mysql_affected_rows returns int32 is native(LIBMYSQL) {*};
     sub bar is native(LIBFOO) {*}
+    sub baz is native(LIBBAR) {*}
+=end code
 
 You can also put an incomplete path like './foo' and NativeCall will automatically put
 the right extension according to the platform specification.