Step by step tutorials for using bindings in D

[Inkrementator]

On Friday, 24 March 2023 at 23:45:15 UTC, eXodiquas wrote:
> Hello everyone,
>
> once again, I am here for your help. My last questions were 
> answered really competently so I try again. :P
>
> So, maybe this is a stupid question, but I have read a lot 
> about Bindings to C and C++ libraries for D. For example the 
> Derelict project (or now 
> [BindBC](https://github.com/BindBC/bindbc-sfml)) is full of 
> them. Now I wanted to use the SMFL2 dynamic bindings.
>
> In my head this works like this:
> 1. I create a project called sfmltest
> 2. I have to get the original SFML2 from somewhere
> 3. I have to place some already compiled SFML2 files somewhere 
> in the sfmltest project
> 4. I have to add the BindBC-SFML dependencies to the sfmltest 
> project
> 5. I have to load the compiled SFML2 files from within my D code
> 6. I can use the bindings.
>
> But as you see, my idea about the whole workflow is pretty 
> vague.
> - What files do I really need from SFML2?
> - Where do I have to store the files from SFML2?
> - How can I tell the D compiler where to find those SFML2 files?
> - Is the overall idea I have about those bindings correct at 
> all?
> - How do dynamic bindings and static bindings differ from each 
> other?
>
> Is there a good resource to learn about those bindings? I 
> currently skim through the books "Web Development in D" and "D 
> Cookbook" and there are also mentions of bindings in them, but 
> they assume I know what I am doing, what I am not. :D
>
> I hope this question or the array of questions to be real is 
> not too stupid.
>
> Thanks in advance and have a nice weekend!
>
> eXodiquas

Hi, there are two things going on here that we need to pick 
apart, unfortunately they are confusingly named. On the one hand, 
we have static and dynamic linking, on the other we have static 
/dynamic bindings.
_This in written from the linux perspective. For windows, most of 
it will still apply, but details like executable names or file 
endings will change_

## Static/ Dynamic Linking

To understand this, we first need to understand a bit more about 
compilation. Again, we have some unpedagogical nomenclature, so 
I'll refer to compilation from Source to Executable/ Library as 
Translation from now on, while the *compilation phase* gets to 
keep its name.

Translation can roughly be divided into two phases: The 
compilation phase and the linking phase.

### Compilation Phase

The compilation phase converts every source file into an object 
file with the ending ".o". They already contain binary code, with 
the exception of symbols (function name, global vars), which are 
still in text form. These symbols can be undefined and point to 
functions from other object files or libraries, but you need the 
types to be able to generate binary code, this is why we need 
binding (more on them later).

### Linking Phase
The linker will combine all the object files into one file. It 
will resolve the undefined (and defined) symbols and insert 
actual addresses.
How it handles external libraries depends on whether you choose a 
static or dynamic library.

#### Static Library
A static library (ending ".a" on linux) is basically just a file 
containing many different object files. If you link against it, 
the library gets bundled into your final executable like the rest 
of your object files. This has the advantage of making your 
executable independent of the environment where you deploy it, it 
won't crash when your user updates his libraries. But it leads to 
space waste when many programs use the same library and also 
forces you to distribute a recompiled version when you just want 
to update a library. This is especially problematic when one of 
your libraries has a security issue as it lengthens the update 
cycle.

#### Dynamic/ Shared Library
Dynamic Libraries (ending ".so" on Linux, ".dll" on windows) get 
loaded dynamically when the program starts. The environment needs 
to provide them. Execute `ldconfig -p` to list all shared 
libraries on the system. `ldd MyExecutable` will list all dynamic 
libraries required by your executable.

# Dynamic Bindings
Dynamic Bindings only work when using the dynamic library.
bindbc-sfml allows you to instead of using the system dynamic 
library loader ld.so to instead manually load the dynamic library.
https://github.com/BindBC/bindbc-loader/blob/master/source/bindbc/loader/sharedlib.d#L320
Afaict, this is only used so you don't need the original SFML 
library on your dev system, it will still be needed on the client 
or if you want to test. I don't understand why you'd want to do 
this, maybe someone else here can illuminate this issue.
Normally, dynamic binding is useful when you want to lazily load 
shared libraries which in some extreme cases can be benefitial, 
or want to be able to hotload plugins.

Now you might wonder: Why does the dynamic linker need the shared 
library present on the dev system and doesn't just internally do 
the same thing as bindbc_loaders?
I'm actually not quite sure, I think it has to do with when 
compiling you can specify many different libraries, and so it 
would have to search for each symbol (functionname) in all 
specified shared libraries at runtime.

# Practical Walkthrough
Two ways to go about this:
1. Get SFML dynamic library somewhere
2. Create a project called sfmltest
3. Add BindBC-SFML dependency via dub
4. Put SFML dynamic library files into the directory where you 
will execute your file.
Here we see that the dynamic bindings looks for the lib in the 
current directory: 
https://github.com/BindBC/bindbc-sfml/blob/a1bc81da5c41ec49257228a29dc0f30ec7e5c788/source/bindbc/sfml/system.d#L215

You can also use static bindings, but that will involve telling 
your linker about the library. I won't go into detail but it 
basically boils down to installing SFML to system directory or 
LD_LIBRARY_PATH and compiling your test project with -lSFML flag, 
or whatever the option is for dub.
If you can install it via your package-manager, static bindings 
might be less of a hassle. And learning the process is worth it, 
you'll need it in the future, since dynamic binding are the 
exception.