MIGRATION commands


PROGRAM NAME

kdarwin - A program to evolve Khoros 1.0 programs to Khoros 2 objects

DESCRIPTION

This program converts a Khoros 1.0 vroutine into a Khoros 2 kroutine object. It does about 70% of the work required to bring an old Khoros 1.0 vroutine program into the new object-based software development system in Khoros 2; some function calls, however, you will have to edit and correct yourself. This program integrates all of the migration tools plus the Program Specification parsing code from 1.0 into a single program. The steps it follows while converting a program are:

1. Create a new kroutine software object in the specified toolbox under the specified object name. Uses the object name for the icon name if [-icon] was not specified.

2. Parse the *.prog file for the vroutine's code and documentation sections.

3. Call uisupdate to convert the *.pane file specified to be Khoros 2 compatible.

4. Call kfixpane to modify the Khoros 2 UIS file output by uisupdate so that the pane will be compliant with the Khoros 2 GUI conventions. This includes updating the short description of the pane (uses the program short description if [-idesc] was not specified), modifying the -R line to hold the fullpath to the binary, and changing the -H line to point to the new help directory.

5. Update the code and documentation files of the new kroutine with the sections from Khoros 1.0 *.prog file. This includes updating the use of the CLUI Information structure to the new name, clui_info which is the name used under Khoros 2. It also inserts code in the appropriate sections to set a variable called program in the main which used to be automatically defined in Khoros 1.0.

6. Call kfix on the loname.c, oname.c, and oname.h to convert the Khoros 1.0 and non POSIX library calls to Khoros 2 library calls.

7. Call mkproto to get the ANSI prototype of the loname routine, and insert it into loname.h public include file.

8. Attempt to run the gnu utility protoize to convert the loname.c file from K & R C code into ANSI C code. Note, this usually doesn't work the first time, and may not ever work if you do not use the GNU gcc compiler for your compiles. However, usually changing your code from K & R to ANSI is just a matter a changing the declaration.

Though this program does most of the work necessary to convert a 1.0 vroutine into a working kroutine under Khoros 2, several steps must be taken by the user to finish the conversion. The code, the documentation, and the uis file of the new object will have to be checked for problems in formatting and checked for sections the migration tools could not handle. The following is a list of things that will have to be dealt with by hand after running kdarwin.

1. The man 3 sections of the Khoros 1.0 program specification will be put into their appropriate section of the routine header in the loname.c file. However, all the roff formatting macros will still be there. So these macros must be removed, and the text should be reformatted to look like a proper Khoros 2 public routine header.

2. All files that were kfix'ed need to be checked for any sets of four # characters in a row. This sign followed by some text indicates that kfix knows the line needs a change, but is not sure how to accomplish the change. Since kfix uses sed to match sections of code, the more complicated C syntax means that it cannot always figure out how to make a change. For example, C function calls that span multiple lines can some times result in this type of error. Also, if a call to a function is used as a parameter in another function call and one or both of those function calls must change, .script index kfix usually cannot figure which parameters belong with each function call. In such a case, you will need to change the code to the correct call, and rearrange the parameters according to the man page. Use kman to find the appropriate format for the call to the Khoros 2 function.

3. In Khoros 1.0 many programs declared external routines that they called in side the variable declaration section of a routine. This practice is bad under ANSI C because the extra declaration is made without the correct prototype causing the correct prototype to be overridden. So, all of these declarations should be removed.

4. Khoros 2 depends on ANSI compliance, so any routines converted must use the ANSI declaration format instead of the K & R one. kdarwin calls the GNU program protoize, if it exists, to automate this process. However, this process usually fails due to syntax errors in the code it is trying to convert. If protoize does fail, it will inform you, and give you the proper command to run protoize on the library source code file again. You will first have to correct the syntax errors in the file before you can run protoize again.

5. Finally, the Khoros 1.0 calls to manipulate the xvimage (1.0 VIFF) structure have been ported to 2 and put in the RETRO toolbox in the vutils and verror library objects. So, in order to get the library calls creatimage, readimage, and writeimage, the toolbox that holds your converted programs will need to include the RETRO public include file, and link against the libraries vipl, verror, and vutils in RETRO. See the Toolbox Programming Manual for instructions on how to makeone toolbox dependent on another.

Note that readimage has been rewritten in 2 to read all data types supported by data services, and forces the data and attributes into an xvimage structure. This fact implies that these programs can manipulate data as in 1.0. However, it also means that you lose the benefits that data services provides, like large data set handling, polymorphic data model, and data propagation. Also, you can lose data if the original format has extra data that does not map nicely into the Khoros 1.0 VIFF structure. The Khoros 2 KDF is such a case, because it is capable of hold 5D data and it can contain extra data segments. The final limitation is that writeimage always outputs the Khoros 1.0 VIFF or xvimage data format.

We encourage you to use kdarwin to quickly move your contributed routines into the Khoros 2 environment; however, it would be best if you follow this quick conversion with a proper re-implementation of the operators using Data Services and one of the available Application Services.

REQUIRED ARGUMENTS

-tb
type: string
desc: Toolbox object to hold the new software object
-oname
type: string
desc: Software object name to use the for the converted vroutine
-cat
type: string
desc: Category Name used in Cantata
-subcat
type: string
desc: Subcategory Name used in Cantata
-description
type: string
desc: The short description of the object
-icon
type: string
desc: Icon Name used for glyph in Cantata

Mutually Exclusive Group; you must specify ONE of:

ALL OF the Mutually Inclusive Group:

-prog
type: infile
desc: Khoros 1.0 Prog filename to get program code and documentation information from
default: {none}
AND
-pane
type: infile
desc: Khoros 1.0 Pane Filename to get program uis information from
default: {none}

-conf
type: infile
desc: Khoros 1.0 conf filename to use to get paths for *.pane and *.prog
default: {none}

OPTIONAL ARGUMENTS

-lname
type: string
desc: Library object to put the vroutine l*.c file into
default: {none}

EXAMPLES

Assume that you want to convert the Khoros 1.0 vroutine vspatial to Khoros 2,
and place it in the Khoros 2 toolbox MYTB.  Also assume you want to convert
the l*.c file to a library object called my_ipl and that your Khoros 1.0
source tree is located in /usr/khoros.  The following command tells
kdarwin
to do this.  Note that the library my_ipl must exist BEFORE you run
kdarwin.  Use craftsman to create this library object.

% kdarwin -tb mytb -oname vspatial -lname my_ipl -cat "Image Proc"
-subcat "Classification (K1)" -icon "Spatial Analysis"
-description "Compute Spatial Feature Operators (NxM Window)"
-prog /usr/khoros/src/vipl/feature/vspatial/vspatial.prog
-pane /usr/khoros/repos/cantata/subforms/feature/vspatial.pane

The output from kdarwin will be as follows:

\f(CW

kdarwin: updating object database [MYTB::my_ipl]
kdarwin: Generating Imakefile & Makefile in src
kdarwin: Generating directory Imakefile & Makefile
kdarwin: updating object database [MYTB::my_ipl]
kdarwin: Generating Imakefile & Makefile in src
kdarwin: Generating directory Imakefile & Makefile
Generating empty ghostwriter files
kdarwin: done generating vspatial man page
kdarwin: done generating vspatial.h
kdarwin: done generating vspatial.c
kdarwin: done generating usage.c
kdarwin: done generating lvspatial.c
kdarwin: done generating vspatial help page
Get PROG information
Update UIS file to 2 format
Update UIS to comply with cantata standard format
Regenerate command line UIS code
kdarwin: done generating vspatial man page
kdarwin: done generating vspatial.h
kdarwin: done generating vspatial.c
kdarwin: done generating usage.c
kdarwin: done generating lvspatial.c
kdarwin: done generating vspatial help page
Update sections of object from prog spec
-- Convert 'vspatial->' to 'clui_info->' in prog sections
-- Update the program related prog sections
-- Update the library related prog sections
Run kfix lvspatial.c
\fIToolbox: MIGRATION
Program: kdarwin
Protoize of 'lvspatial.c' failed.  This implies that the code still will not
compile because of some cases that the automatic update routines cannot handle.
You must fix these problems, and re-run protoize by hand.  This can be
accomplished by cd'ing to the src directory for the library that contains
\'lvspatial.c\', and typing:

protoize -c "-fstrength-reduce -fpcc-struct-return -fwritable-strings -ansi -I/research/devel/mirage/work/mytb/include -I/research/devel/mirage/khoros/include -I/research/devel/mirage/retro/include -I/usr/local/motif/include -D__sun -D_POSIX_SOURCE" $MYTB/objects/library/my_ipl/src/lvspatial.c Keep fixing problems and reprotoizing until it produces a lvspatial.c.sav file. Update the man page database for the library kdarwin: Finished Generating a man page for the function \'lvspatial\' in \'$MYTB/objects/library/my_ipl/man/lvspatial\'\fP kdarwin: done generating my_ipl library headers kdarwin: done generating my_ipl man page Run kfix vspatial.c Run kfix vspatial.h kdarwin: done generating vspatial man page kdarwin: done generating vspatial.h kdarwin: done generating vspatial.c kdarwin: done generating usage.c kdarwin: done generating lvspatial.c kdarwin: done generating vspatial help page kdarwin: updating object database [MYTB::vspatial] kdarwin: Generating Imakefile & Makefile in src

\fP

This initially converts the routine. After you have fixed the syntax problems and prototypes as indicated above in the above example, you can compile this program. Note that in order to compile, you need to make you're toolbox dependent on the RETRO toolbox. This only needs to be done once, and the resulting mytb.def file should look similar to the following one. The path to the retro toolbox will differ as per your specific site's installation. Note that the order on the TOOLBOX_LIBRARIES line for the retro libraries is important. Also, libraries that exist within mytb should be listed BEFORE the retro libraries.

% cat `kecho -echo path -tb mytb`/repos/config/imake_conf/mytb.def
#ifndef _mytb_def_
#define _mytb_def_
KCOM toolbox.def
KCOM toolbox configuration file for toolbox "mytb"

/* * #include <TOOLBOX>_INCLUDE - specify toolboxes this toolbox depends on. * * The following list are the toolboxes that the cplustest toolbox * directly depends on. The order of this list is important, because it * tells the imake system the order for include and library paths. * * For example: * * #include BOOTSTRAP_INCLUDE * * includes the bootstrap toolbox. */

/* -toolbox_include_toolboxes */ #include RETRO_INCLUDE /* add this line */ #include DESIGN_INCLUDE /* -toolbox_include_toolboxes_end */

/* * TOOLBOX_INCLUDE - extend search path for include files * * The +<= variable syntax prepends the toolbox include path to the variable * TOOLBOX_INCLUDE. If TOOLBOX_INCLUDE was previously undefined, it will * just set it to the -I path below. This is necessary so that the toolbox * include directory is included in the compile commands. */

/* -toolbox_include_path */ TOOLBOX_INCLUDE +<= -I$(MYTB_PATH)/include /* -toolbox_include_path_end */

/* * TOOLBOX_LIBDIR - extend search path for libraries * * The +<= variable syntax prepends the toolbox library path to the variable * TOOLBOX_LIBDIR. If TOOLBOX_LIBDIR was previously undefined, it will * just set it to the -L path below. This is necessary so that the toolbox * library directory is included in the link command. */

/* -toolbox_library_path */ TOOLBOX_LIBDIR +<= -L$(MYTB_LIBDIR) /* -toolbox_library_path_end */

/* * TOOLBOX_DEFINES - optional symbols for additional preprocessor definitions * * The +<= variable syntax prepends the toolbox defines to the variable * TOOLBOX_DEFINES. If TOOLBOX_DEFINES was previously undefined, it will * just set it to the value below. This is necessary so that the toolbox * defines is included in the compile and link commands. */

/* -toolbox_cpp_defines */ TOOLBOX_DEFINES +<= /**/ /* -toolbox_cpp_defines_end */

/* * Addlibrary(lname, type) - macro to add library to load line for toolbox * * The following list are the libraries that the cplustest toolbox * depends on. This list must be in reverse order. The AddLibrary macro * takes two parameters. The first is the library archive name, and the * second is one of C, FOR, or X. Note, different library types will * automatically be ordered correctly. * * For example, suppose this toolbox has three libraries: two C libraries named * libfred.a and libwilma.a and one X library named libxdino.a. If the fred * library depends on the wilma library, then you would use following * AddLibrary lines: * * AddLibrary(wilma, C, $(MYTB_LIBDIR)) * AddLibrary(fred, C, $(MYTB_LIBDIR)) * AddLibrary(xdino, X, $(MYTB_LIBDIR)) * * Note, the placement of xdino could have been anywhere, because it is * of a different type than fred and wilma. */

/* -toolbox_libraries */ /* -toolbox_libraries_end */

/* * BINDIR - where to install binaries * LIBDIR - where to install libraries * KLD_RUN_PATH - used on systems with shared libraries to define the * path to the directory where the libraries are. * * Define the directories where the program binaries will be installed and * where the library archive files will be installed. */

BINDIR = $(MYTB_BINDIR) LIBDIR = $(MYTB_LIBDIR) KLD_RUN_PATH +<:= $(MYTB_LIBDIR)

#endif /* _mytb_def_ */ /* Don't add after this point */

%

SEE ALSO

ghostwriter(1), kfix(1), kfixpane(1), mkproto(1), uisupdate(1), protoize(1)

RESTRICTIONS

This program was specifically designed to convert from vroutines to kroutines, so using it on any other program type will produce strange results.

REFERENCES

Migration Toolbox Manual, Toolbox Programming Manual

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.