DIRECTIONS ON COMPILING/PORTING/USING JOKER

CONTENTS:
1. What is it?
2. Directory structure
3. How to port Joker to another platform
4. Impatient person's guide to porting Joker
5. Compiling Joker on your platform
6. Using Joker
7. Contact information and legal stuff


1. WHAT IS IT?

Joker is a cross-platform virtual compiler for the HyperTalk programming language with advanced extensibility. You can simply plug in additional commands, functions, object types etc. while maintaining its English-like syntax.


2. DIRECTORY STRUCTURE

There are six main levels:

projects - Project files and makefiles for the different compilers. There is one folder for each platform, containing one folder for each compiler, with all compiler-specific files in that folder.

includes - Header files for Joker. There is one folder for each platform, containing only header files.

sources - Source code files for Joker. There is one folder for each platform. Besides actual source code files, I also keep any resource files or similar in here, but only if they're not specific to a particular compiler.

docs - Documentation on Joker. Docs auto-generated from header files also go in here. One folder per platform.

support - Files that aren't really part of the project, but are useful when debugging/maintaining/developing. Contains the "hypertalk" folder with scripts used in testing Joker.

binaries - Executable files generated by the various project files and makefiles go here. One folder per platform with one folder per compiler.

Note that there are two "pseudo-platforms" in the "includes", "sources" and "docs" folders:

The "common" platform, containing all the stuff that truly is cross-platform (i.e. the "ANSI" platform). If you need to change any of the code in the "common" folder, one of us two has screwed up.

The other is the "generic" platform. The "generic" platform is a castrated version of all platform-specific source and header files, with code to emulate features as much as possible in ANSI code. Where that isn't possible, a couple of comments in the code and then an error message to the user that this feature isn't supported have been written into the source code files.


3. HOW TO PORT JOKER TO ANOTHER PLATFORM

Joker is laid out to be portable. That much on the theory. In fact, you always have to rely on certain hardware specifics. So, we just make some assumptions that work out for most platforms people will want to use Joker on. Joker assumes an ANSI/ISO C++ compliant compiler. It tries to achieve as much as possible using the ANSI/ISO Standard C libraries and ANSI/ISO C++ STL. Everything those don't cover, is done using a tiny contingent of platform-specific code.

To start a new port, make a copy of the "generic" folders in "includes" and "sources", and rename them to something that lets developers familiar with the platform recognize it. E.g. HP Unix would probably go in a "hpux" folder, Windows would go in a "win" folder, etc. Finally, rename the "Gen" prefix of the file names to something resembling your platform as well.

Then set up your project or makefile in a folder named after your compiler (which goes into a folder named after your platform in the "projects" folder) to generate an application and put in it all files from the "common" folders and your new platform's folders, along with everything else a simple command-line application needs on your platform. For most platforms, that should be enough. Get it to compile, and you're half way there.

Once you've played a little with your new port, you'll notice that some things don't work. You'll get error messages when trying to access remote URLs, for example. Now's the time to actually do the work: Go to your new platform's folders (the ones that you copied from "generic") and go through the files in there. Read the comments (or at least the ones labeled as "FIX ME!" and use the information to insert your platform-specific code.


4. IMPATIENT PERSON'S GUIDE TO PORTING JOKER

Copy any folders named "generic" in sight, rename them to your platform's name (e.g. "windows", "hpunix", "solaris", ...), rename the "Gen..." files to start with a short form of your platform's names. Then create a project/make file with all files from your platform's folder and the "common" folder. Then revisit the former "Gen..." files and read the "FIX ME!" comments to know how to port them.

You should put your project files in the folder Joker/projects/platformname/compilername/ (where platformname and compilername are the actual names of your OS and compiler)


5. COMPILING JOKER ON YOUR PLATFORM

To compile a copy of Joker on your platform, go into the "projects" folder and locate the folder corresponding to your operating system. In that folder, locate the folder for your compiler and open the makefile or project file in there. Compile that.

If you cannot find your platform, chances are Joker hasn't been ported to your platform yet. In that case, you will want to have a look at section 3 of this Readme and port Joker yourself.

If you cannot find your compiler, but you can find your platform, try doing the steps in section 3, but instead of copying the "Generic" folder and renaming it, use the folder for your platform that already exists.


6. USING JOKER

To use Joker, check out the JokerDoc.txt and Syntax.txt files in Joker/docs/common/ and any documentation pertaining to your platform in Joker/docs/ .
For further reading, I suggest the following:
- Any books on HyperTalk, in particular "Cooking with HyperTalk" by Danny Goodman and Apple's manuals, especially the HyperCard Script Language Guide
- The source code. I spent waay too much time making the code unreadable by excessively commenting it to have you not reading it.


7. CONTACT INFORMATION AND LEGAL STUFF

Joker is (c) Copyright 1999-2002 by M. Uli Kusterer, all rights reserved.

Reach Uli at:
E-MAIL:    witness@weblayout.com
           witness@mac.com
           witness.of.teachtext@gmx.de
           witness@t-online.de
WEB:       http://www.weblayout.com/witness
           http://homepage.mac.com/witness
           http://home.t-online.de/home/witness




(c) 2002 by M. Uli Kusterer, all rights reserved.
