Add generated files for OO API for C language to distribution

[sim1984]

There are many programs written in C. At the moment they use the legacy isc API. But at the moment the isc API is not being developed and it is impossible to add new functionality to such programs. I know that with the help of CLOOP we can generate an OO API for the C language. But most developers are not aware of this. Moreover, they are afraid if some generated C interfaces get into their program, which over time can change in FB and they will become broken.

There are real examples of this need. Recently I made a patch for Firebird 4.0 data type support for the pdo_firebird driver for PHP. I simply bound all the new data types to strings, since PHP has no other types in which the values ​​of the new FB types could be placed. And it works. With one exception, for TIME[STAMP] TZ data types, you cannot set the display format. This is easily solved in the OO API, but PHP is written in C, and it uses the isc API. In my opinion, it is quite strange to include two generated files fb_api.h and fb_impl_api.c in the pdo_firebird source code to solve this problem. I think maintainers will simply not accept such a patch, because the files are generated and may violate their coding standards. It would be a different matter if they were included in the Firebird installation and were located in ${fb_root}/include like other API files.

[AlexPeshkoff]

С generator was not tested on real data for rather long time. I will take a look at it but this may be not as trivial as adding files to distro.

BTW:

Moreover, they are afraid if some generated C interfaces get into their program, which over time can change in FB and they will become broken.

Is there an example of backwards-incompatible change of interfaces in released versions?

[sim1984]

Is there an example of backwards-incompatible change of interfaces in released versions?

I don't remember any, but that's not the main problem. The main problem is that the lack of ready-made files greatly complicates the implementation of new features in projects written in C.

I made a mini-example of using the C OO API. It's certainly not ideal, but it just helped me figure out how it works. https://github.com/sim1984/fb_c_oo_api_example

After I figured it out, I made a patch for PHP pdo_firebird php/php-src#15230

In this form, it looks dubious, but it is even more difficult to justify the need to add two files to the project that seem alien to the project.

If cloop were at least enabled in the Firebird build, then third-party builds could be configured to automatically generate these files. But cloop is only in the source files, it is not documented, and it does not even have help on command line options. That is, in fact, it is more of a tool for Firebird developers, and not for developers who want to generate Firebird API for their programs.

My wishes consist of three points:

1. The cloop tool should be included in Firebird builds. It should have help on command line options.
2. It would be desirable to have a ready-made OO API file for the C language, as it is done for C++ and Pascal.
3. It would be nice to make at least one example of working with the OO API in C.

[AlexPeshkoff]

On 7/26/24 09:20, Simonov Denis wrote: There are many programs written in C. At the moment they use the legacy isc API. But at the moment the isc API is not being developed and it is impossible to add new functionality to such programs. I know that with the help of CLOOP we can generate an OO API for the C language. But most developers are not aware of this. Moreover, they are afraid if some generated C interfaces get into their program, which over time can change in FB and they will become inoperable. There are real examples of this need. Recently I made a patch for Firebird 4.0 data type support for the pdo_firebird driver for PHP. I simply bound all the new data types to strings, since PHP has no other types in which the values ​​of the new FB types could be placed. And it works. With one exception, for |TIME[STAMP] TZ| data types, you cannot set the display format. This is easily solved in the OO API, but PHP is written in C, and it uses the isc API. In my opinion, it is quite strange to include two generated files |fb_api.h| and |fb_impl_api.c| in the pdo_firebird source code to solve this problem. I think maintainers will simply not accept such a patch, because the files are generated and may violate their coding standards. It would be a different matter if they were included in the Firebird installation and were located in include like other API files.

Denis, one more question. Do you see big need to include source file fb_impl_api.c into include directory? For me building of static library (and having it in default library path) looks much more logical. What do you think?

[sim1984]

The presence of fb_impl_api.c into include directory is really illogical. There are two options: either a static library, or declare these functions built-in.

If you use a static library, then in theory you can hide the details of all structures.

[AlexPeshkoff]

I've decided to not add cloop binary to distribution - with ready-for-use plain-C API files it makes no sense.
@sim1984 - please review the result, after it suppose I can backport it to FB5.

[sim1984]

Ok. The only remark is that I didn't see lib/fb_c_api_ms.lib generated for msvc, but it seems that this is not for you.

I'll try to check C api under Linux tonight.

[sim1984]

In C, for functions without parameters, it is advisable to write void inside the brackets.

struct IMaster* ISC_EXPORT fb_get_master_interface(void);

[sim1984]

#include <ibase.h>

struct IMaster* ISC_EXPORT fb_get_master_interface(void);

/* This file was autogenerated by cloop - Cross Language Object Oriented Programming */

#ifndef FB_C_API_H
#define FB_C_API_H

I think declaring the function fb_get_master_interface and include <ibase.h> before the header guard is not very good.