🔒 Locked

(another) AngelScript binding generator

Started by Gyrbo Sep 20, 2007 at 8:08 AM 4 replies 4.5k views

Original Post

Sep 20, 2007 at 8:08 AM

I was wondering if there was any interest in an automatic AS binding generator. As a basis for the bindings, I would use the pdb file that MSVC generates (by using the DIA SDK). The tool would read the pdb and output either of these formats: 1. A C++ file that can be compiled into your project would would contain all the required binding code. This would require you to compile your project twice: once for generating the pdb and parsing it and a second time for linking in the generated .cpp file. I'm not sure how well this would integrate with build systems. The advantage would be that this file can easily be used by other operating systems besides windows. 2. A sort of serialized version of the internal AS state. All information that is required is contained in the pdb file. The advantage of this approach would be that you only have simple postprocessing step. On the other hand, this file would probably expose more information that you want about the internals of your program. This file would also only be usable on windows (since it contains function pointers, etc.) A small description file would specify which classes/functions should be included. I haven't started any actual implementations, so I'd like to get some feedback on this idea before I start on this. If I still have some time after this is finished, I might try using an approach based on the actual source (probably using GCC-XML). But since this would probably be harder to do and not be as reliable (calling conventions, ...?), I'd prefer to use the pdb approach first.

WitchLord

Sep 20, 2007 at 9:38 AM

If you were to base the binding on the pdb file, you would only be able to generate this on Windows machines, right? For Windows developers that's fine, but for Linux, Mac, and console developers it wouldn't be of much use.

I don't think the AngelScript function signatures can be generated automatically from the C++ code, since the syntax is not exactly the same. For example a C++ pointer can be represented as either an AngelScript reference or handle.

In my opinion a tool for generating the binding code should be based on a configuration file that describes which types/methods/functions etc should be bound. It should also be able to validate the bindings automatically by comparing the AngelScript function signatures with the C++ signatures to make sure they match. The tool can then be added to the beginning of the build chain to catch any changes in the C++ code that invalidates the bindings in the configuration file.

For my own part I'm going to provide a way for the application to validate the functions signatures automatically upon registration. This will work something like this:

funcId = engine->RegisterGlobalFunction("void func()", asFUNCTION(func), asCALL_CDECL);ValidateFunction(engine, funcId, func);

This would be a templated function that is able to determine the parameters and return value of the C++ function, which it will then compare against the types of the registered function. SiCrane has shown me that it is possible to automatically determine the calling convention via templates as well, so that too will be validated.

Not sure when I'll have the time to do this though, but it's definitely something that I'll do.

Gyrbo

Sep 20, 2007 at 10:36 AM

The tool itself would only work on windows, but its generated code is potentially portable. That is assuming that other compilers don't default to a different calling convention.

I hadn't giving the C++ <-> AS binding difference enough thought, it seems. Handles are probably the most difficult to do automatically since you have to add the refcount to the class. The refcount also needs to be updated appropriately. References need to correct in/out specifier, too.

My intention was to make the configuration file as light as possible (only specifying the class/function names and offering to automatically bind all methods of a class). The reason for this is that AS itself is already pretty user friendly. If the configuration file is too complex, there would be no added value over simply calling RegisterXXX manually.

Making a validator for the code was one of the things I was planning once this was finished. It might be better to start on that, but if you're going to provide this yourself using inline code, it might not be worth it. I'd try to do it using templates, but I can't really wrap my head around all the required concepts.

abrken

Sep 22, 2007 at 12:27 AM

Suggestion :

Why not using Doxygen ?

Doxygen has a C++ parser and can generate XML files.

This way, with some comments (special tags recognized by Doxygen) around the class members and methods you could be able to make your tool generate what you need.

AbrKen

Gyrbo

Sep 22, 2007 at 3:22 AM

That actually seems like a pretty nice idea. From what I gather, custom commands would be a bit of a hack, but workable. I'll have to do some experiments to see if this an actual viable solution, but it seems to best method for now.

Thanks for the hint abrken!

Gyrbo

Oct 21, 2007 at 8:55 AM

I've been working on this for a while and I have a very basic first release. You can download it here: http://gyrbo.madoka.be/YAASB/YAASB-20071021.zip. It's called YAASB (Yet Another AngelScript Binder).

The zip includes everything to get you started. To use it, you'll have to get your header files processed by doxygen. You can do this by going into their directory and executing doxygen.exe with the supplied Doxyfile as an argument. This will create a folder called "xml" with all the required files for YAASB to work. You pass this folder as an argument to YAASB.exe. It sounds complex, but it's quite easy. The following commands will generate and output.cpp file with all the bindings it can generate

doxygen.exe DoxyfileYAASB.exe -y -o output.cpp xml/

It will most likely generate lots of inout references, so you'll need to enable ALLOW_UNSAFE_REFERENCES for it to work. Handles are planned for a later release. If you only want to include specific files, remove the "-y" switch and put the following in each file you want to use:

/*! @file @use{recursive}*/

If there are any classes/namespaces/methods you don't want includes, you can prepend them with the following comment:

//! @use{no}

If you already use doxygen for your project, you can add these actions to existing comments. In order for them not to show up in the documentation, add the following to your Doxyfile:

ALIASES += use{1}="\xmlonly<yaasb use=\"\1\" />\endxmlonly"

Things that aren't included, but planned:
- Handles
- Inheritance
- Downcasting functions
- Arrays (using STL containers?)
- Templated classes (using typedefs)
- Wrappers for const char* to strings
- Wrappers so generic calling conventions can be used

Any comments are greatly appreciated. I'm also looking for header file to test the code on.

Topic Locked

This topic has been locked by a moderator. New replies are not allowed.