Subject: HOWTO -- stub out dialogs on other platforms
From: Paul Rohr (paul@abisource.com)
Date: Thu Mar 02 2000 - 18:14:36 CST
By now, the process of implementing a new dialog should be pretty familiar.
You figure out what the dialog should do, rough it out on your platform of
choice, localize it, and then figure out how to move as much of that logic
as possible to platform code.
abi/docs/AbiSource_DialogFramework.abw
http://www.abisource.com/mailinglists/abiword-dev/99/September/0171.html
It's not your responsibility to actually *implement* the dialog on other
platforms, but you do need to stub out the other platform implementations in
ways which don't break the build. Here's how to do this for AP dialogs.
(The procedure for XAP dialogs is left as an exercise for the reader.)
1. Finish your platform first
------------------------------
Nobody likes to port a moving target, so you'll want to have as complete an
XP implementation as you can which runs smoothly on your platform. Don't
forget to include a screenshot!
2. Clone the stubs
-------------------
For all platforms other than yours, locate the relevant stub file:
http://www.abisource.com/mailinglists/abiword-dev/00/March/0070.html
(New platforms get added from time to time, so you're probably better off
checking your view of the tree to see which stubs you're responsible for
now.)
Since those stubs are always being built along with the rest of the product,
you should be able to copy and clone each one safely. Follow the directions
at the bottom of the .cpp file, and don't forget to replace that comment
with an explanation of anything the person doing the port will need to know.
Yes, they can crawl through your platform-specific code to learn what you've
done, but it's a lot easier all around for you to just paste in a quick
description of the work you had in mind. When it's time for you to port a
dialog that someone else wrote, you'll appreciate that they returned the
favor for you.
3. Update both makefiles
-------------------------
A platform-specific dialog needs to get added to *two* makefiles:
abi/src/wp/ap/<platform>/Makefile
abi/src/wp/ap/Makefile
The first makefile builds the actual OBJ for that ABI_FE, while the second
makes sure that it gets linked. Note that you've probably already updated
the second makefile for your platform, so you just need to deal with the
first set of platform Makefiles.
4. Add the DeclareDialog macros
--------------------------------
Also, be sure to update the #includes and DeclareDialog macros in the
following header files:
abi/src/wp/ap/<platform>/ap_<platform>Dialog_All.h
Skipping this step won't break the build, but it will cause crashes at run
time, so be nice and do it anyway.
5. Review your work
--------------------
This one's easy. Before applying a big change like this, take a look at
your work to see if anything odd crept in.
First, check to see which files you've modified by issuing some variant of
the following command:
cvs -n -q update
This will show you a list of all the files you've added or modified, which
is a very easy way to notice that you've skipped one of the header files or
makefiles on platform FooBaz. (I make this mistake all the time.)
Second, look at the changes themselves. If you're submitting a patch, skim
the patchfile to make sure everything looks reasonable. (Or you can just
issue the appropriate CVS diff command.) As with any change that touches
each platform, you should be able to see a very common pattern, with the
same idiom being repeated on each platform. Any difference that jumps out
at you should probably be looked at.
6. Watch Tinderbox
-------------------
Once your stuff gets checked in, watch Tinderbox over the next few hours to
make sure everything builds cleanly:
http://www.abisource.com/tinderbox/showbuilds.cgi?tree=AbiSource
Build failures at this point should be pretty rare, but if they do happen,
you should be able to figure out what went wrong and submit the appropriate
"Fixed build" checkin or patch.
That's it!
Paul
PS: If I've left anything out, be sure to reply to this message, so that
everyone else knows, too.
This archive was generated by hypermail 2b25 : Thu Mar 02 2000 - 18:09:11 CST