FB header translation

[dkl]

Tools to help with *.h to *.bi header translation:

• h_2_bi
• fbfrog

Further information:
DevBindingCreation

List of headers/bindings included in FB:
External Libraries Index

The latest FB development version including headers can be retrieved via Git:
DevGettingTheSourceCode

If you translated additional headers, or updated existing ones, we'd be happy to include them into FB! You can post them here in the Libraries forum, or submit them to the fbc patch tracker on Sourceforge. If you prefer to fork the fbc Git repository and make some commits on your own, no problem, it's no issue for us to pull in the updates.

[Lachie Dazdarian]

Anyone proficient in header translation willing to write a beginner level tutorial on it, using a tool of his choice? In my opinion, that would be much more beneficial at this point than individual efforts. Today I tried to explore h_2_bi and was met with terms and problems I'm completely unfamiliar with. I'm also not sure how much knowledge of C is required to be able to attempt this.

What would really benefit willing/aspiring contributors who don't know where to start is some basic rundown of the whole process (dummy-level explanation), explanation of key terms, example of manual translation of a part of some lib, side by side .bi equivalent of .h code, what happens when you translate, common errors, what often needs to be done manually and how, testing, explanation of C code basics necessary to read .h files.

Might sound like a drag to people who know their way around this, but if they want more helping hands, this would be the most constructive way to do it. I'm lost.

[TJF]

Might sound like a drag to people who know their way around this, but if they want more helping hands, this would be the most constructive way to do it. I'm lost.

I agree, we should have good tutorials!

What would really benefit willing/aspiring contributors who don't know where to start is some basic rundown of the whole process (dummy-level explanation), explanation of key terms, example of manual translation of a part of some lib, side by side .bi equivalent of .h code, what happens when you translate, common errors, what often needs to be done manually and how, testing, explanation of C code basics necessary to read .h files.

I did my best to summarize this in the file ReadMe.txt (and LiesMich.txt) in the h_2_bi.zip archive. Not sufficient? Why? What do you miss?

Anyone proficient in header translation willing to write a beginner level tutorial on it, using a tool of his choice? In my opinion, that would be much more beneficial at this point than individual efforts. Today I tried to explore h_2_bi and was met with terms and problems I'm completely unfamiliar with. I'm also not sure how much knowledge of C is required to be able to attempt this.

Can we cooperate to improve the ReadMe.txt? I guide you in your first header translation and you extend the ReadMe.txt with the accumulated knowledge.

[Lachie Dazdarian]

Can we meet in chat? #freebasic at FreeNode

[Lachie Dazdarian]

For example, the explanation of parameters.

-S2 // two space intend
-nw // names und wrapping
-P_iALL_oWR_oUD // combination of multiple -P settings

I'm dummy terms.

I transladed new FMOD Ex and got a bi file, but many "'??? no type for FUNC, macro expansion" messages? What's the next step?

What is name mangling '_' ?

The message(s) I got:

[TJF]

-S ==> indent
When h_2_bi creates structures like TYPE or ENUM and also when it creates a parameter list (in wrap mode) an indentation is used. By option -S you can choose how the indentation will be done: either by a TAB character (-S0 - zero = default) or by a specified number of space characters (-S3 means 3 space characters). You don't need this at the beginning.

-n ==> names in parameter lists
When h_2_bi translates a parameter list in a function prototype it only needs the variable types to create sufficient FB code, but by default the names are also included (if a name is specified in the original C code). By option -n the parameter lists have no variable name.

-w ==> wrap parameter lists
Weather a parameter list should be in a single (maybe long) line or be wrapped after the FUNCTION/SUB name and each parameter (indented by a TAB or any other -S specification).

Name mangling
is used to solve naming conflicts. A naming conflict may happen when a variable in the C code is named as an FB keyword (FB has more than 370 keywords). In this case the header needs a different variable name, which gets created by mangling the original name by the specified character "_" in this case (or any other STRING - in my first headers I used "_TJF"). Name mangling also is used for a C typedef when the type and the name are identical and for nested TYPEs or UNIONs. The FB header guideline recomments the "_" mangling.

'??? no type for FUNC, macro expansion
this error occurs when h_2_bi tried to translate a function prototype but it couldn't identify the functions type. Mostly this happens when a marco is used in the function declaration. To solve this conflict you have to identify the macro name and copy the macro declaration from the C header in to the .h2bi file, section MACROS. This makes h_2_bi expanding the macro (to C code) before the translation. Macros can have parameter lists even with variadic parameters (in C syntax).

BTW:

Some time ago I made FModEx-4.32.4_TJF.bi. I can post my .h2bi configuration file when I'm at my main box again. It should contain most of the parameters you need.

[TJF]

I just checked your messages and I like to add one more hint:

For the first test your folder structure is OK. But when you're confident with h_2_bi I recomment to re-organize the files on your HD to the structure described in the ReadMe.txt file. (One folder for each library, separated from the h_2_bi folder.)

[Lachie Dazdarian]

Cool. I would like to see the conf file you have. Didn't know anyone attempted FMOD EX translation before.

But as you can see, header translation is a serious business that calls for a tutorial(s), explaining all these issues, as well as showing examples to deal with them.

Thanks for the help so far.

[TJF]

But as you can see, header translation is a serious business that calls for a tutorial(s), explaining all these issues, as well as showing examples to deal with them.

Yes, a serious business! That's why I wrote h_2_bi in cooperation with AGS.

Unfortunately I loose the capability of writing good tutorials when I delve deeply into a subject, especially when I learn by trail and error as I did when developing h_2_bi. I started to write a tutorial (approximately 30 pages in German jet) but I learned that I need a co-author to finish it.


Anyway, I didn't explain yet:

-P_iALL_oWR_oUD // combination of multiple -P settings
The option -P is to set any parameter for h_2_bi. Currently there are more than 70 switches, find details in the source file h_2_bi.bi. All switches can be set or unset by the -P option in the following way:

• -P is the option to start any switching
• the underscore is to show that one more switch is following
• the next character selects the group of switches. There're five groups: C = config file, I = input handling, O = output handling, P = protocol generation and T = translation. A capital group letter is to set the following switch to ON, a group letter in lower-case sets the switch to OFF.
• the next two or three letters select the switch (find details in the above mentioned file)

One -P option can be used for each switch (ie -P_iALL -P_oWR -P_oUD) or several switches can be chained up in one -P option (ie -P_iALL_oWR_oUD).

The switches are executed one after the other. Ie -P_oWR_OWR will first switch OFF wrapping mode and then switch ON wrapping mode, so wrapping is ON after that option.

In this example the switches are:

• _iALL sets all switches from the input group to OFF. This means no translations will be done. The C source is transfered to the .bi file just as comments. The reason for that switch is to concentrate to just a few input types that are switched ON after the _iALL switch. Ie a following _IBT sets the translation of block type to ON and the .bi file will contain only TYPE block translations (and the rest of the C source as FB comments).
• _oWR sets the WR switch (wrapping of parameter lists) in the group O (= output) to OFF. (This will reset the effect of the option -w, which is an abreviation for -P_OWR.)
• _oUD sets the UD switch in group O to OFF. UD stands for unsave define lines. When h_2_bi finds characters in a #define line that it cannot handle, then it marks these #define as unsave by an error comment and makes the hole line a FB comment. OFF means that the line gets active in the .bi file (still with the error comment at the end).

Cool. I would like to see the conf file you have. Didn't know anyone attempted FMOD EX translation before.

One of the reasons that h_2_bi collects the parameters in a config file is that these information can be used for further updates. So here you are:

Code: Select all

/* place the name of the start file here */
fmod.h

__PARAMETERS__(){};
-f

__FOLDERS__(){};
fmodapi43204linux/api/inc

__HEADERS__(){};

__TYPES__(){};

__MACROS__(){};
#define F_CALLBACK
#define F_API F_STDCALL
#define F_STDCALL
//#define F_CDECL
//#define F_DECLSPEC
//#define F_DLLEXPORT

__POST_REPS__(){};

__START_BI__(){};
' This is file FModEx-4.32.4_TJF.bi
' (FreeBasic binding for FModEx, a sound library)
'
' translated with help of h_2_bi.bas
'
' Licence:
' (C) 2010 Thomas.Freiherr@gmx.net
'
' This library binding is free software; you can redistribute it
' and/or modify it under the terms of the GNU Lesser General Public
' License as published by the Free Software Foundation; either
' version 2 of the License, or (at your option) ANY later version.
'
' This library is distributed in the hope that it will be useful,
' but WITHOUT ANY WARRANTY; without even the implied warranty of
' MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
' Lesser General Public License for more details, refer to:
' http://www.gnu.org/licenses/lgpl.html

#IFDEF __FB_WIN32__
#PRAGMA push(msbitfields)
#ENDIF

#INCLIB "fmodex-4.32.04"

__END_BI__(){};
#IFDEF __FB_WIN32__
#PRAGMA pop(msbitfields)
#ENDIF

Note: option "-f" in PARAMETERS section is a mix of several parameters. I use it for the productive code at the end of the translations process. (It generates short and fast code, ie no comments, no names and no wrapping in parameter lists, ...)

Note: by default you can call a macro inside another macro (here F_STDCALL in F_API). But h_2_bi stops recursive macro expansion after the first iteration (to avoid endless loops). Use option -P_tMA to switch OFF recursive macro expansion.

[goldbaby777]

http://sourceforge.net/projects/jesuschristsuns/

the programming i built above link uses fmodex development release......... with freebasic......... if you want to check that out.....

[counting_pine]

Hi goldbaby777, have you created an up-to-date fmodex translation, or are you just advertising your project here?

[goldbaby777]

it is source code to an up to date pretty much translation to fmodex........ because the usual fmodex.bi you guys created doesn't allow me to use fmodex, i loaded the library in manually in the source code......