AmiZilla Project Specification #4
Project Number: 4
Name: Create a GTK->Reaction emulation layer
Specification Version: 1.0
Date: 3 Nov 05
Written by: Anton Reinauer - amizilla@...
Project Manager: Anton Reinauer (for now)
Email: amizilla@...
Website:
http://www.ants.nameAddress: 12 Asbury Crescent
Campbells Bay
Auckland
New Zealand
Overview:
Create a GTK and GLib emulation layer for Reaction on AmigaOS3.9 and AmigaOS4.
Description:
The GTK Library is one of the two main Gadget/Widget/Windowing systems on Linux
(and some other OSes). GLib is the low-level core library that forms the basis
of GTK+ and GNOME. It provides data structure handling for C, portability
wrappers, and interfaces for such runtime functionality as an event loop,
threads, dynamic loading, and an object system. Note: that GLib provides some
direct GTK support, and so the layer will use some Reaction Functions in places.
Reaction is the Gadget/Widget/Windowing systems on AmigaOS4 (also available on
AmigaOS3.x)- we're not sure yet how similar Reaction on AmigaOS3.9 is to
Reaction on AmigaOS4- but we'll find out soon!
You will create a GTK and GLib emulation layer using Reaction Function calls to
emulate the
GTK/GLib calls, so that Linux programs like Mozilla can be more easily ported to
AmigaOS4. All GTK Function calls, need to be wrapped to Reaction, but only some
of the GLib calls need porting, as some of the Linux GLib code can be compiled
as is.
Goals (in general order):
Familiarise yourself with the SourceForge website, in particular with the
GTK->MUI and AmiZilla projects.
http://sourceforge.net/projects/gtk-muiGet a SourceForge user account (if you don't already have one).
Get access for your SourceForge user account to the CVS (for writing), for the
GTK->MUI, and AmiZilla projects. Note: you don't need specific access to these
for downloading, just for uploading.
Learn about the Concurrent Versions System (CVS), and how to use it to auto-sync files on a CVS server (in this case SourceForge), and on your system. Initially you will just be downloading files, but later you will be using CVS to update any work you have done to the Server too. Note: there are several easy to use CVS programs with GUIs on WinXP, like TortoiseCVS.
Create a new SourceForge project called GTK->Reaction, and give the other people
involved in the GTK->Reaction project access. Note: don't give access out to
anyone, as people with access can write (or delete) source code files!
Get a development environment up and running (Cross-compiling, and WinUAE on WinXP), and familiar with GCC, and the Bash (or BSH (/bin/sh)) command line terminal, and basic command line commands like ls, cp, mv, mkdir and rm (type in `man command' like man cp, to get help on a command). Also, learn what tar,
gzip, bzip2, and grep are used for and get used to using them from the command line- note: there also are ways of accessing some of these through a GUI (like WinZip). You can use the GUI versions later, but initially it's a good experience to get your hands dirty using the CLI!
Research how to make an AmigaOS3.9 Shared Library, as your code must be re-entrant, and can only use local variables. Global variables can be used if really needed, by initialising them when the Library is opened by your program (known as per-opener data). All other data is provided to functions as parameters, as variable data or pointers to memory/Objects. Also research how to make shared libs on AmigaOS4, there's Includes and a program to make this easy.
Read up on the GTK, GLib, MUI and Reaction APIs (Application Programming Interfaces)- you don't have to know MUI fully, but enough to have a good overview and to understand what's going on in the GTK->MUI emulation layer.
Start on GTK, GLib and MUI first, and then later on, Reaction- you may want to start on these early, as it can get confusing jumping from one to the other-trust me, it can drive you a bit crazy! :)
Look through oli's GTK->MUI project code to get a general idea of how to make a GTK emulation layer, and what GLib calls need porting, and which can be compiled, as they are.
Start porting GTK and GLib Function calls to Reaction on AmigaOS3.9, as source code that can be included into test programs- we'll work on putting it into a Shared Library, and porting it to AmigaOS4, later.
Check that the functions, that don't need to be ported, are compiling and
working ok (note: you may need to port some functions first to test these
properly).
Test the ported functions, by including your source code into GTK test programs (that come with the GTK SDK (Software Development Kit)), or make up some of your own if needed.
Document what you have coded, as you go along, either in the source code, or in separate documentation (in HTML format, so it can be put on the Internet), where appropriate. Also, keep a History page up to date, documenting changes made to each version of your source, and what files have been modified.
Upload each version of your source to the SourceForge CVS, after sufficient testing and code review. Get feedback from users on any bugs, and fix them, and document bug fixes in History file.
When all functions have been ported and appear to run well, go "Yay!" :)
Download (through CVS) the AmiZilla sources and compile with your sources included, and get the exe working- may require tweaks to your code or modification of AmiZilla source! Note: you'll be working closely together with the NSPR and GDK teams to get this working!
Create a Shared Library for AmigaOS3.9 from your sources, and test with test programs, and then with the AmiZilla source (with your sources no longer included with the AmiZilla source).
Port GTK->Reaction to AmigaOS4. Read up the appropriate AmigaOS3.9 and OS4 API documentation to work out which AmigaOS3.9 calls are the same on AmigaOS4, and which require changing, and change the appropriate OS3.9 calls to OS4 ones.
Test Functions as above on OS4, and get the GTK/GLib/GDK libraries working with OS4 port of AmiZilla. Note: again, you'll be working closely together with the NSPR and GDK teams to get this working.
Go "Double-YAY", and go down the pub for a drink to celebrate! :))
Notes:
That we'll only be writing functions in C, not C++, as most functions will be very small, and using C++ Classes would be unnecessary, and inefficient. But note that C++ functionality like `//' for comments can be used, and maybe C++ string manipulation functions like `cout' be used too. Note: that work on AmiZilla sources may involve using C++ Classes.
You'll be be compiling for two different Platforms (AmigaOS3.9 and AmigaOS4) which will require Pre-Processor commands, to compile different sections of code depending on which Platform is being targeted (done with `make' files). Also, some thought would then have to be given for possible CPU differences (68k, and PowerPC) too, like accessing shorts and longs on odd memory boundaries, and Endian issues for Bit reads and manipulation (all of which can be solved with Macros (Endian issues by Byte Order Macros in GLib) and Pre-Processor commands).
Debugging will be done, firstly by `Code Review' (also known as White-Box debugging), so you look thoroughly through your code to look for any mistakes, or logic errors. If this is done enough, then you will find that you will end up with very few bugs in your code, and won't get users moaning at you! ;) But seriously, 15 minutes of code review, can literally save you hours of trying to find and fix a run-time bug!
Secondly we will use small test programs to check the ported code, either as in Black-Box testing, where parameters are fed in to a function, and output tested, or by running test programs and checking that they are performing correctly (the latter will probably be used mostly, as a lot of these functions are graphically based).
Also, we will be doing `Defensive Programming' where appropriate- ie: we will test that Function parameters are within correct bounds, so at worst, they may make our program misbehave, but won't crash our code!
The project has specific goals for each student, but also there will be some goals that will have to be achieved by working with other students/programmers
in a team. Each member of the team, may have specific knowledge and experience on different areas of the AmiZilla project. They will need to provide this knowledge, and help coding and debugging in their own specialist areas, to help the team achieve combined goals, much more quickly and efficiently!
This part of the project is just as important, as the individual bits (if not
more so), as it is how many real-world projects work, and good communication between the team can be critical! We will create separate mailing lists from the main AmiZilla one to make this easier, and I would strongly encourage students to regularly get together from the beginning, and discuss what they're doing on the project(s) over coffee!
!!!
