ADD: Support for dynamic linking first version that can be compiled u…

[PascalCorpsman]

Hello all,

based on the discussion ev1313/Pascal-SDL-2-Headers#78 (comment) i wrote a little FPC Transpiler and switched now my complete work over to this repository.

In Order to create the least impact possible, i choosed to do "inplace" modifications for the code switchings for dynamic / static linked version.

The static linked version is 99% unchanged (only needed to rename the two overloaded functions from sdl2.pas).

The dynamic linked version does compile under Windows64 and Linux64, under Linux64 i was also able to test the joystick part (and that worked ;) )

So if you choose to migrate this PR then all users who are using the SDL2.pas at least need to do this step:

(*

• If you get a compiler error with missing file

• just create a file namend "sdl2_cfg.inc" in your project folder and

• insert the following content:

• ---------- Content of file ---------
  {*

• set this define if you want to use dynamic linking instead of static linking

• ! Attention !

• Not all functions are "ported" yet, see existing "working" code on how to

• port missing functions.
  *}
  {.$DEFINE SDL_DYNAMIC_LINKING}

• ---------- End content of file ----------

• ! Attention !

• If you use the dynamic link feature, don't forget to call the SDL_LoadLib

• function.
  *)

And yes there is still plenty work to do, to have a fully supported dynamic linked SDL2.pas, but beside the already mentioned differences you could stay at the static linked version with nearly no change and at least the "basic" dynamic linked version does now exist ;).

I think if you merge this code base, maybe other interested users could finish the work i started here (y).

[PascalCorpsman]

One Question it seems that i upladed the files with the wrong line endings, which one is the one of the project, than i will try to correct this ?

[Free-Pascal-meets-SDL-Website]

Thanks for this overwhelming PR; wow but a hell of a commit :D

I guess we will need some time to review this.

[suve]

We're using \n line endings in the project; your PR seems to rewrite most of the files to use \r\n instead, hence the humongous diff.

[PascalCorpsman]

ok i reworked the code to change the lineendings, now there are a lot less changed lines :)

[suve]

Why create a separate commit? Please amend the original one, instead.

Looking through the PR, this creates an SDL_DYNAMIC_LINKING define which changes all function definitions to a pair of typedef + function pointer. The idea's simple, but it creates a lot of extra churn in the code, to the point where I'm wondering if it'd make sense to store the definitions in some templated form and have a program generate the final .pas/.inc files.

Another thing is that the nomenclature is wrong - dynamic linking is what we're doing right now. This switches the library to runtime loading.

[PascalCorpsman]

sry i do not know how to amend a commit.

if i rename

{.$DEFINE SDL_DYNAMIC_LINKING}

to

{.$DEFINE SDL_RUNTIME_LOADING}

then we solved the nomenclature thing.

Your point according the "Churn" thing is surely right, but maybe this should be part of work after you merged the PR ?

[Free-Pascal-meets-SDL-Website]

@PascalCorpsman May I ask, did you add all the ifdef's by hand? Or did you use some kind of a script?

Could you please change the function pointer suffixes to "func" instead of "fun". I mean, this library is fun indeed, but this suffix choice if just funny :D.

One thing I see as kind of a problem: To stay consistent in the future, merging this (without the proposed template solution) would force the project to add the ifdefs for all new definitions. On the other hand this is a "hot" feature and it may be worth it.

I'm also a little bit concerned about the pasdoc generator, it will not recognize the comments anymore, especially since pasdoc also has no groupBegin/groupEnd feature to my knowledge.

[PascalCorpsman]

May I ask, did you add all the ifdef's by hand? Or did you use some kind of a script?
Lucky me, the code in the .inc files is really good structured, so i could do this with some easy string manipulation functions, and yes initially this was a program written in Lazarus, i only needed to adjust less than 10 functions by hand to get it compiled.

I attached the program, but be aware that this code is a complete mess, as it was created to run exactly once and then thrown away ..
inc_converter.zip

Could you please change the function pointer suffixes to "func" instead of "fun". I mean, this library is fun indeed, but this suffix choice if just funny :D.
did ;)

as i already suggested, if you come up with a good template solution this should be done, all i wanted to do, is showing how it could be done and that it is doable. And at least for my fpc_atomic project it already does the trick ;)

[Free-Pascal-meets-SDL-Website]

Looking through the PR, this creates an SDL_DYNAMIC_LINKING define which changes all function definitions to a pair of typedef + function pointer. The idea's simple, but it creates a lot of extra churn in the code, to the point where I'm wondering if it'd make sense to store the definitions in some templated form and have a program generate the final .pas/.inc files.

Maybe our original static definitions should be the template.

@PascalCorpsman I really appreciate your commitment a lot, I still wonder if there is a more elegant way of doing it. As @suve pointed out, the extra definitions overload our translation code. Also it contradicts our principle to just translate the basic headers one-to-one. Extra features should be kind of separate. - I still had no time examining your code though. :(

[PascalCorpsman]

I still had no time examining your code though. :(

i recognised this ;), as i was yesterday able to test the code under Windows and there it crashed due to missing conversions. After fix 1d87255 it now works like intended (at least on Windows and Linux).

And yes if there is a more elegant way to support runtime linking and the orig way i would be really interested in that too, maybe we have luck and some clever guy is reading this and pinpoints the clever solution g

By the way, if you look at the code you will recognize really soon that the port is not completed, as i only needed the joystick parts i only ported them and showed at least one way how the rest could be done, so again finding a elegant way and then porting the complete codebase to this would be the best way (y)

[JernejL]

Any chance for this to be merged? i would prefer to use dynamic linking version (that allows me to have much better checks and load library from a common dynamic library folder for the game)

[Free-Pascal-meets-SDL-Website]

Hey @JernejL ,

sorry for the delayed response. I missed it.

I fear it cannot be merged the way it is. It would completely change the whole code base and add hundreds of IFDEFs. I could imagine using the added code and re-arrange it in a way that the original files are untouched.

I'm basically thinking of something like this:

1. sdl2.pas is the only part where we have a large IFDEF around the inc-files. The original set of inc-files which are used by default (IFNDEF SDL_RUNTIME_LOADING). The second set of inc-files has a different name changed by a suitable suffix maybe. They are called if SDL_RUNTIME_LOADING is set.
2. The second set of inc-files is created by a program which replaces all functions/procedures by their typedef/func-pointer pair as done in this PR. Everything else gets replicated (comments, constants, ...).

However, it will probably not be that simple and work right away.

Any volunteers? :D

@suve What do you think about this? I mean, if this worked here, we could apply it to SDL3 as well.

[PascalCorpsman]

hmm,
you mean like this ?

maybe i am able to adjust my little hacky tool to do it so ..

after a little thinking, i would prefer this more:

with this the filenames would stay the same, and all runtime things are separated into their own subfolder..

[PascalCorpsman]

OK, it was less work than expected,
i now moved all "new" code into subfolder "runtime" and let the "old" code unchanged as much as possible.

[Free-Pascal-meets-SDL-Website]

Great, looks promising so far. I'm about to check it out as soon as possible (time restraint here atm.). Also waiting for a response of @suve.

Best regards

[Free-Pascal-meets-SDL-Website]

@PascalCorpsman

Now I looked deeper into your contribution and tested it successfully. If it plays out well, it is indeed a very valuable extension of this project, thanks for your effort. Nevertheless, there are some things which have to be done before a merge is possible.

1. Please squash commit a5e0478 into commit 19a2176 by the interactive mode of git. See: https://www.w3tutorials.net/blog/how-do-i-squash-my-last-n-commits-together/ for a step-by-step description. After that you need to force-push to update the history in this PR.
2. Your naming convention is different than the one we use. Keywords (function, var, type, begin, end, string, ...) should be lower-case. Any other descriptor should start with a capital letter (Result, False, True, ...). This is important to make your contribution blend in perfectly with the project.
3. The functions SDL_LoadLib and SDL_UnLoadLib should have a comment describing their purpose and especially that these are no native SDL functions (but rather part of this project). In the SDL_LoadLib function the fall back if no lib-string is given, is SDL_LibName. This fact should also be mentioned.
4. You added a cfg file to set the SDL_RUNTIME_LOADING flag. Why wouldn't you just add the flag to SDL2.pas? We have a flag there already (WANT_CWCHAR_T). Is there a deeper reason for this?
5. I'd prefer the "normal" inc-file block being above the dynamically linked one. Maybe use {$IFNDEF SDL_RUNTIME_LOADING}.
6. It's a bit nasty but the comments describing a function should be right above the var declaration. Only this way it will be recognized and displayed in, e.g. Lazarus. Maybe your hacking tool can do this?
7. Maybe we should add some kind of test. (this is for later, I guess)

Okay, these hints are not ordered by any priority, except for the very first hint, which is crucial to keep our history somewhat clean. I would advice to start with this one, too.

I would have done some things myself but I wouldn't want to mess with your contribution, unless you agree with that.

Best regards
Matthias

[PascalCorpsman]

@Free-Pascal-meets-SDL-Website
i tried my best with your step1, thanks to ChatGTP if it was, what you wanted, if not please tell and i will try to ask a "human" to help me out with this, but this than can take much longer.

for your 2., do you have a codeformator that you use, which i can run on the code as well ?

3. done

for 4. i use the code in multiple projects and don't want to change the lib code as it is a lib. By including a .inc file i can set / not set the define in this .inc file, this gives me the ability to use the same code without the need of changing it. I recently figured out, that this can annoy users as they always have to create the .inc file, my newest solution to this problem is to define the needed define in my lazarus project => this would remove the dependency for the .inc file and would give the user also the ability to adjust the code as he wants to. If you want i can change this to a "comment" that describes the define and let the user chose

5. done

6. i don't get this, can you showcase me please a location in the code where this occurs ?

7. shure any idea how to do ?

[Free-Pascal-meets-SDL-Website]

@PascalCorpsman

Thanks! Here is my response.

1. Seems good now.
2. If you use Lazarus, I would try the search-and-replace function. Many code editors have a similar feature. Lazarus also provides the JEDI Codeformatter (Menue --> Source code --> JEDI Codeformatter) , didn't use it very much though.
3. Could you please use curly brackets for these long comments instead of the double-slash.
4. I suspected something like what you described. - Yes, please just add the out-commented define like //{$ ...}
5. Great. please use all-caps for the compiler directives, so {$IFNDEF ...} instead of {$ifdef ...}. Same for the other ones.
6. Okay, in Lazarus for example, if you place your cursor right onto a SDL function, usually after a second a window pops up which shows a function description. Actually the content of these pop-up windows is just the content of the comment right above a function declaration in the source code. In your case the comment is shown in Lazarus only, if you place the comment right above the variable definition of a function.
7. (not yet)

Best regards
Matthias

[PascalCorpsman]

@Free-Pascal-meets-SDL-Website

OK, i think we really make a progress ;).

Here is how far we are so far (at least from my opinion)

1. done
2. done
3. done
4. done
5. done
6. i now understood what you want, but that's tricky, i need to write a new "hacky" tool, also it seems that not all variables have a comment, that will take a bit, but i'll try my best
7. idle
   So please confirm, that you see it the same, or write what you think is not done yet (y)