
	autoport

	(Semi-)Automatic porting of jMax 2.5 packages to jMax 4.0.

	By Carl Seleborg
	Copyright (C) 2003 by IRCAM-Centre Georges Pompidou, Paris, France

	Author and collegues can be contacted at the following address :
		<jmax@listes.ircam.fr>

	Please read the disclaimer at the bottom of this file.



	 ###########################################################################
	# THE AUTOPORT SCRIPT AND THIS FILE ARE STILL "WORK IN PROGRESS" AND ARE    #
	# NOT QUITE FINISHED YET. THE SCRIPT WORKS IN THE GREAT LINES, BUT IT WON'T #
	# DO ALL IT WAS INTENDED TO DO YET.                                         #
	 ###########################################################################




* WHAT IS AUTOPORT ?

Autoport is a Perl-script written to help jMax-package developers port their
code to the new version of jMax, 4.0. Indeed, some changes in the API have
been made from version 2.5 to version 4.0, and packages developped for the
former version will not work with the latter.

We could have simply listed the changes in the API, leaving developers to
review their whole code line by line and track down things that ought
to change - and ultimately, they will have to do just that anyway. But to
make their life easier, we decided to create this script to assist them
in modifying their code.


* WHAT DOES IT DO ?

Autoport basically works this way : it starts by finding all C source files
in the specified directory (.c and .h files). It reads them one by one a
first time to gather some information about the package. Once that is done,
it starts reading them in again, one at a time, and makes some changes
in the code. Everything it touches, autoport marks it with a comment, so
you can easily find the spots where autoport has been and check that it
has done it's job correctly. Once all changes have been made, autoport
rewrites the file back to disk, overwriting the original file.

Autoport tries to copy the whole source-directory to another destination,
thus backing up your source code before fiddling with it. However, you
should definitely keep a BACKUP of it somewhere safe, because one never
knows.

Here is a (non-exhaustive) list of what autoport tries to do :

	- Remove the fts_module_t definition. This is not required anymore
	  with jMax 4.0 (see below) and autoport will comment it out.

	- Rename and the package's initialization function to
	  packagename_config(). This is how jMax finds the function now
	  (as opposed to version 2.5, with which this initialization
	  function was to be specified in the fts_module_t structure).
	  Autoport also removes the "static" keyword for that function
	  if it finds one : declaring that function static would prevent
	  the symbol packagename_config() from beeing exported, and
	  jMax would not find it when loading the module.

	- Modify method declaration for objects. In particular, the
	  function fts_class_init() now takes as parameters the constructor
	  and destructor function for that class, which means that defining
	  those methods for the fts_s_init and fts_s_delete messages is now
	  unnecessary, and autoport will try to remove those  method-
	  definitions if it finds them.

	    As for the other methods, they are now defined using the
	  fts_class_inlet*() and fts_class_message*() class of functions.
	  Things have changed here a bit since version 2.5 of jMax. Before,
	  you had to specify which inlet was to receive what kind of data,
	  even with symbols. From now on, when your object receives a symbol,
	  it does not matter which inlet it receives it on, so you just use
	  fts_class_message() do declare what method to call upon receiving
	  such a message. Basic data types like numbers, floats..., however,
	  are still associated with an inlet.

	- Change the return-type of the object_instantiate() functions in your
	  package. These are now void-functions.

	- Replace a few function names that have changed with their new name.

	- Warn you when you are using obsolete features, like alarms. Autoport
	  will put a small note in your code where it finds such a feature to
	  tell you what has changed.


* WHAT DOES IT NOT DO ?

Here is what autoport does *not* do :

	- Be smart. Autoport is a Perl-script, and it works based on
	  regular expressions. Those are powerful tools, but they are still
	  limited and are nowhere near as good and accurate as a true C parser.
	  Autoport will not work properly if you are using "strange" constructs
	  in your code, like super-killer-macros, and it might even trip over
	  a type cast or other feature requiring parentheses or commas. But rest
	  assured : autoport tells you everything it does, and keeps the original
	  as a comment, so if something went wrong, you can easily correct it by
	  hand.

	- Autoport is not  able to "generate" new code if needed. This means
	  for instance that if you had an fts_alarm_t object in your module (which
	  must be replaced by an fts_timebase_t object ; see doc for details),
	  autoport will not create the equivalent code for you, using a timebase
	  instead of the old fts_alarm_t. Instead, it will just warn you that
	  you are using an obsolete feature.

	- Modify Makefiles and the general architecture of the source-tree.
	  Currently, autoport only modifies C source files.

	- Autoport gets confused when you have several modules in the same
	  source-tree. It will probably rename all module-initialization
	  functions to the same package_config() name.

	- Serve coffee. Like I said, regular expressions are not powerful enough
	  to do that yet.


* FUTURE IMPOVEMENTS

	(If you have brilliant ideas, tell us about it! - <jmax@listes.ircam.fr>)


* DISCLAIMER

Here's the rule :

YOU ARE USING AUTOPORT AT YOUR OWN RISK. THIS PROGRAM WAS
CREATED TO ASSIST YOU IN YOU WORK OF PORTING YOUR SOURCE
CODE FROM JMAX 2.5 TO JMAX 4.0. IT WAS NOT CREATED TO DO
THE WORK FOR YOU, AND IT IS CERTAINLY NOT A RELIABLE TOOL.
YOU SHOULD MAKE BACKUPS OF YOUR SOURCE FILES BEFORE USING
IT, SINCE IT WILL MODIFY THEM. NOONE BUT YOURSELF CAN BE
HELD RESPONSIBLE FOR ANY LOSS OF DATA NOR FOR ANY HARM CAUSED
BY THE USE OF THIS TOOL.

It's clear. Not our fault.

