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.
Mutually Exclusive Group; you must specify ONE of:
ALL OF the Mutually Inclusive Group:
AND
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.paneThe 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:\fPprotoize -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
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 */
%