The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

Allegro 4 development

From Allegro Wiki
Jump to: navigation, search

Note: this page may be somewhat outdated

API and ABI compatibility

Until 4.2.0, The stable branch of Allegro is backwards and forwards API and ABI compatible. The unstable branch is backwards API compatible.

For 4.3.x, there is no compatibility. This is a WIP version - it is unlikely that things may break, but if there is a reason for it, we may have to change something.

I had no idea what this is about when first hearing it, so here a simple description. (API stands for Application Programming Interface, and ABI for Applications Binary Interface.) API means all the publicly available symbols (functions/variables/macros) available at compile time. API backwards compatible means, if you take an old source of an Allegro-using program, and recompile it with the newest Allegro, compilation will still succeed (only with some warnings about deprecated symbols). API forwards compatible means, if you take a new Allegro program's source, and compile it with an old Allegro, it will also succeed. This means of course that no new symbols may be introduced.

ABI means all the available symbols (functions/variables) available at runtime (as opposed to compile time above). Taking windows DLLs as example, ABI backwards compatible means, if you take an old binary of an Allegro program, and run it with the newest Allegro DLL, it will still run without problems. Analogous, ABI forwards compatible means, if you take a new binary of your Allegro program, and run it with an old DLL, it will also work.

So in short, inside the stable branch, there can be no changes at all except bug fixes. Within unstable, there can be any changes.

If you apply a patch changing API/ABI compatibility (WIP only) - all such changes should be noted in the documentation in the sections about API and ABI compatibility (Does this apply to 4.3?): http://alleg.sourceforge.net/onlinedocs/en/api.html http://alleg.sourceforge.net/onlinedocs/en/abi.html

Creating/Applying a patch with SVN

To create a patch, you can use, from the top-level source directory (e.g. allegro/4.3):

svn diff 'name_of_modified_file' > 'name.diff'

This will create 'name.diff', containing all your local changes compared to the version on the server.

svn diff 'name_of_modified_file' > 'name.diff'

This will contain only the changes of the specified file.

If you add or remove files, you can use "svn add" or "svn rm", then create the patch. As long as you don't commit, no actual changes will be made.

To apply such a patch (created by someone else) locally, you do, also from the Allegro base directory:

patch -p0 < 'name.diff'

This also works for multiple files at once, or newly added or deleted files - the patch will contain all the changes.

If the patch is tested and ready to be included with the next WIP distribution, send it to the developers mailing list (or the sourceforge tracker) -especially if you don't are a developer and there's not enough attention by a developer on the list).

On the list, there will probably be a lot of complaints and nitpicking about the patch, making it seem like it is not wanted. But just keep fixing what is complained about, and resubmit improved versions, until finally it meets our high standards :) We are glad about every improvement, the nitpicking is just so the code stays as clean and maintainable as possible, allowing others to understand it with minimal effort. The code style is described in the docs, in the section The Allegro Hacker's Guide: http://alleg.sourceforge.net/onlinedocs/en/ahack.html

Make sure to not use any TAB characters in the part of code you modify (but leave old tabs in-tact, we don't want to introduce lots of whitespace changes for them, it just makes tracking of changes harder).

Once a patch was tested by some people and can be considered ready, and there is agreement on its usefulness (and the maintainer (dictator) doesn't veto it, or decides to include it), you can commit.

To commit changes as a developer, simply use:

svn ci -m"detailed description of changes"

Modifying the code (applies to 4.2)

Adding a new global function or variable

First, always document what it does with a comment in the sourcecode.

Internal

In case the new symbol is not to be intended to be part of Allegro's API, its name should start with an underscore. Such symbols are only used by Allegro itself, or by certain addons which have to access internal parts. And it should be declared in the header include/allegro/internal/aintern.h.

Public

There are two differences to internal symbols: A public must be declared somewhere in include/allegro/*.h - depending on which module it belongs to. And it must be found in the documentation, so you need to add an entry to docs/src/allegro._tx.

AL_INLINE

AL_INLINE is a macro with two purposes. In header files it is used to define inline functions. In src/inline.c all inline functions are additionally defined as non-inline functions. That means Allegro can work with C compilers that don't support inline functions, and functions can always have their addresses taken.

Adding an example

Allegro's examples are meant to be simple, one-source-file programs, to demonstrate a specific topic. Assume, we want to add a new example to demonstrate Allegro's mind reading capabilities. We name it exmind.c, and place it into the examples/ directory.

To get it integrated into the build process, simply edit makefile.lst, and add it to ALLEGRO_EXAMPLE_FILES and ALLEGRO_EXAMPLE_EXES. Don't forget to run "make depend" after that, to update the dependencies and the example actually will get build with make.

Next, documentation. First, the example should be listed in examples/examples.txt. Then, you might think about adding it to allegro._tx manually - but no, some ingenious person wrote a python script to do this all for you. How does it work? Let's suffice to say, it almost is like mind reading. Simply run:

python misc/genexamp.py > examp.diff patch -p0 < examp.diff

Maybe manually check examp.diff before applying to see what it does. It magically created documentation, with cross references and everything.

That was all, a new example has been added to Allegro, congratulations!

Adding a new driver

Each platform has a list of the possible drivers for each subsystem. In most cases there will only be one driver of each type, e.g. one keyboard driver, one mouse driver, but there can be any number of each. This list is stored as an array called _SOMETHING_driver_list. As an example, the keyboard driver list for the BeOS port is in src/beos/bkeydrv.c. If you look in that file you will see that there is only one possible keyboard driver for BeOS, which has an identifier KEYBOARD_BEOS (defined in allegro/platform/albeos.h) and points to the structure keyboard_beos. The TRUE at the end of the entry marks the KEYBOARD_BEOS driver as autodetectable. If it was FALSE it would only be used if the user specifically asked for it in a config file (which is only possible for some types of drivers, mainly graphics, sound and mouse drivers).

Continuing with our example, keyboard_beos is defined in src/bkey.c. As you can see, it has the type KEYBOARD_DRIVER, which can be found in include/allegro/keyboard.h. The first four fields of KEYBOARD_DRIVER are common to all SOMETHING_DRIVER types. I think they are documented in the Allegro Hacker's Guide so I will not repeat it here. The rest of the fields are different for each type of driver. In the case of the keyboard driver you can find out what each is for by reading src/keyboard.c. Most fields will be function pointers that drivers need to implement. In the case of the BeOS keyboard driver, the functions are actually in a separate file src/beos/bkeyapi.cpp (the BeOS native API is in C++).

Adding a new platform

  • Install C compiler (probably gcc) for target.
  • Obtain a suitable libc for the target.
  • Add new target to fix.bat and fix.sh. See fix.bat and fix.sh
  • Add makefile fragment
  • Create source tree for video driver
  • Create source tree for audio driver
  • Create Keyboard, Joystick and Mouse drivers
  • Create System Driver

TODO

Allegro Architecture (4.2)

General

AllegroArchitecture

Windows

WindowsArchitecture

Mac OSX

MacOSXArchitecture

Unix

UnixArchitecture

BeOS

TODO. Maybe if OpenBeOS (actually, they gave it a completely weird name by now, don't remember though) catches on, this may get some revival. If Allegro still exists by that time.

DOS

TODO. Well, I don't know why anyone would start working on that port again, but it is still there in any case and actually still works..

NintendoDS

NintendoDSArchitecture

Build System

The build process broken down. Requirements for the allegro build system, canidates to replace the current build system and what needs to be done.

Current System

Automake.

Problems

Automake is not very cross-platform friendly. Having to remember to pre-configure, run autotools, fix.sh, make and so on and so forth.

Replacement Canidates

  • Others

Making a release

There are different releases: The release of a new major version, which happens only rarly, e.g. release of 4.0.0 or 4.2.0. There are usually several beta versions and release candiatates before it, in order to let no bugs go into the final release. Of course, there can always be bugs, so for 4.0.0, 4.0.1, 4.0.2 and 4.0.3 followed - bugfix releases on the stable branch.

The other type of release, which is supposed to happen much more frequently, are releases of the unstable branch, or WIP releases, like 4.1.14 or 4.3.1. They happen as soon as there are enough changes or new features that we think it is time for users to try out the new version and report back bugs/problems/experiences.

About what has to be done for an actual release, this was sent to [AD] by Eric Botcazou: ReleaseInstructions The newest version of that document can be found in SVN as misc/release.txt.

Once that has happened, the web process takes off, following:

http://alleg.sourceforge.net/docs/webmaster_instructions.html#releasing-a-wip-especially-for-other-allegro-developers

The web maintainer currently is Grzegorz Adam Hankiewicz.