Suggestion: explicitly describe of ".o called .so" link magic

[LeeTibbert]

Introduction

@olofwalker
Thank you for this project. I found that it repaid close study.
The handling of nativeClangOptions allowed me to find &
correct one of those "apparently working & fatally flawed"
bugs in my build.sbt.

If imitation is the sincerest form of regard, I cribbed
the melding of C makefile & build.sbt. Totally understandable
after the fact, but my build.sbt foo never got me there.

Suggestion

Please consider the following suggestion, offered in the spirit of
continuous improvement.

The README.md uses the concepts "library" and,
especially "shared library".

build.sbt runs the makefile, producing the shared library in the \target directory
A custom library path is added to nativeClangOptions so the stub library is found

While the GNU ld documentation occasionally refers to an object (.o) file
as a library, the by far more common use of "library" refers to a
static (.ar) library/archive or a shared (.so) library. In particular,
"shared library" almost always indicates a .so.

This project seems to use a bit of slight of hand. It compiles a .o object
file (gcc -c) with a .so extension on the output file. The critical line
is in the makefile.

Since this project is offered as an example, I believe that it would
be easier for people to follow along and understand if the ".o as .so"
idiom was clearly & prominently explained in the README.md.

Mentioning that the trick does not currently work for .a static libraries
(because they need to be on the right of scala-native out.ll and clangNativeOptions puts
things on the left) would also help people avoid likely mistaken
extrapolations. Agreed, the core project should be correct before worrying
about

A possible future example

Making example projects too complicated reduces their worth, so let
me offer a suggestion for a possible future example.

This project worked for me with proper .so files if I:

1. Removed the -c from the gcc line, thereby generating a proper .so shared library.
2. Did one of the following, fielder's choice:

• Used ld -rpath magic to specify fixed location: (usually development only, use CAREFULLY, if at
  all for production).

// This allows link to succeed                                                  
nativeClangOptions ++= Seq("-L" ++ baseDirectory.value.getAbsolutePath()
                                ++ "/target")

// This allows run to succeed.                                                  
// CAUTION: static location is for development only.                            
//          For production use see GNU ld documentation (/usr/local/lib/foo).   
// Of course, the .so must really be on that path, with proper protections.     
nativeClangOptions ++= Seq("-Wl,-rpath,"
                             ++ baseDirectory.value.getAbsolutePath()
                             ++ "/target")

• Placed the .so in one of the ld "standard locations" (requires root)

• Used LD_LIBRARY_PATH when executing the image

$ LD_LIBRARY_PATH=<replace_with_your_path> <replace_with_your_executable>

• Created & used a small helper script:

#!/usr/bin/env bash
#
# RESTRICTION:
# This file expects to be located & executed in ${PROJECT_ROOT}/bin.
#
# There is a lib/ld-linux.so.2 --library-path PATH EXECUTABLE form
# that is supposed to work, but I could not get it to find the .so.
# A problem for another day.
#

PROJECT_ROOT=$(pwd | sed "s/bin$//")

# The .so library must exist, with proper protections, somewhere
# along the new LD_LIBRARY_PATH.

export LD_LIBRARY_PATH=${PROJECT_ROOT}/lib:$LD_LIBRARY_PATH
exec ${PROJECT_ROOT}/bin/test_libmycfunctions_so.exe