\begindata{text,538380552}
\textdsversion{12}
\template{help}
\define{global
}
\define{keyword
}


\chapter{CreateInset: Generate Source Files for a New Inset

}
\section{What CreateInset is

}\leftindent{
To create a new inset, one must create seven or eight files, much of the 
initial contents of which are rather standard.  The -createinset- program 
creates a directory and copies a standard set of files into it, changing names 
systematically to a name of your choice.  To create your own inset, change the 
parts marked '$$$' in each source file.}


\section{Quick reference

}\leftindent{
}\leftindent{The command is 


	createinset \italic{insetname}


where \italic{insetname} is the desired name for the inset.  This creates a 
subdirectory of the current directory with the name \italic{insetname} and 
copies seven files to it from /usr/andrew/lib/null/, changing file names and 
contents to reflect the chosen inset name.}


\section{Warning}


\leftindent{The \italic{insetname} should be nine (9) letters or fewer. 
 Although there may be some good psychological reasons for short names, there 
is a technical reason as well:  a file named \italic{insetname.help } is 
generated and some systems do not support file names longer than fourteen 
letters.}


\section{Files Installed

}\leftindent{
The command 


	createinset \italic{inset} 


creates directory ./\italic{inset} and installs the following files in it:


	Imakefile	  controls the -make- program

	\italic{inset}.ch	  class header file for data object

	\italic{inset}.c	  implementation of data object

	\italic{inset}v.ch	  class header for view

	\italic{inset}v.c	  implementation of the view

	\italic{inset}vt.c	  test driver for the view

	\italic{inset}.help	  prototypical help file


In each file there are places to change to create your own inset.  These 
places are marked '$$$', either just before an entire section to change or at 
the end of a line to change.


Instead of revising inset.help, you can delete it and edit inset.help; 
 because of the extension it will be editted with the standard help template 
which includes all sections you might want in a help file.

	

}
\section{Makefile 

}\leftindent{
To generate a makefile, use the genmake command.  This will read the Imakefile 
and generate a Makefile.  The new Makefile has all the usual targets of 
Makefiles created with genmake;  see /usr/andrew/doc/ImakeMacros.d and the 
description in Section 2.3 of the README file that comes with the Andrew 
distribution.  In particular:

\description{\leftindent{
(no target)  -  compiles and links to create the .do files

all - same as (no target)

test  -  does all and also builds the insetnamevt program

Makefile  -  rebuilds this Makefile (genmake must have been run earlier to 
make an initial version of this Makefile)

depend  -  appends dependencies to the Makefile

install - copies the created objects to a destination tree

dependInstall - does both depend and Install

tidy - removes generated and useless files that have not been installed

clean  -  removes all generated and useless files}


}To install in locations other than /usr/andrew/... the value of DESTDIR 
should be set to the root of the tree instead of /usr/andrew/.  This can be 
done by editting the Makefile or by giving the new value on the make command 
line:


	make all DESTDIR=/usr/me/obj/

}

\section{Programming Environment

}\leftindent{
The Makefile in the new directory assumes an environment that makes it 
possible to develop multiple insets, possibly cooperating.  The test versions 
of them all will be used.  In order for this to work, do this:


1. All of the insets should be developed in directories which are children of 
one parent.  For example, to work on insets jack and jill, they could be in 
directories /usr/me/src/jack and /usr/me/src/jill.


2.  There should be a destination tree, say /usr/me/dest, with child 
directories dlib and include.


3.  In order to utilize the include files from the /usr/me/dest/include 
directory, its location has to be passed to the Makefile.  This can be done by 
defining a value for LOCALINCLUDES either by editting the Makefile or on the 
command line:


	make test LOCALINCLUDES=/usr/me/dest/include


4.  In order to utilize the new .do files, you need to tell the dynamic loader 
where to find them.  This is done with a CLASSPATH; the lines in your ~/.cshrc 
would look something like this:


	setenv CLASSPATH /usr/me/dest/dlib:/usr/andrew/dlib/atk


5.  To get the files installed, the full command would be


	make Install DESTDIR=/usr/me/dest LOCALINCLUDES=/usr/me/dest/include


It is possible to put a single Imakefile in the parent directory /usr/me/src 
that will cause compilation of all the child directories.  Three steps are 
necessary:


1.  Create in the parent a file called `subdirs` whose contents are a sequence 
of lines each containing the name of one of the subdirectories.


2.  In the parent Imakefile put the line


	#define IHaveSubdirs


3.  In the parent Makefile include an assignment to the make variable SUBDIRS:


	SUBDIRS = jack jill


After taking these steps, recursive make targets are defined in the Makefile 
generated in the parent directory.  These targets will do the corresponding 
operation in the parent directory and all subdirectories:  Makefiles, Install, 
 dependInstall, Tidy, Clean.


}
\section{Debugging}


\leftindent{To debug insets one useful tool is to print out information at 
crucial points in the code.   For example, typing ESC-^D-D to the null will 
turn on the 'debug' switch in nullview and cause a trace of entry to and exit 
from routines.  


For more serious problems, the gdb debugger has proven useful.  You can apply 
gdb to the test driver installed by createinset:


	gdb nullvt



The most useful gdb commands are help, run, bt, frame, print, next, continue, 
and break.  Control-c halts execution of the program.


If your inset works fine in the drivers but fails when loaded into a document 
or application, you can debug it by starting from an unstripped version of the 
runapp object.  At CMU this would be done as:


	gdb  /afs/andrew/`sys`/itcobjects/itc/andrew/atk/apps/runapp


After gdb has read this program and its symbol tables, you run ezapp, or some 
other app, like this:

	run -d ezapp -d filename


The first -d prints information about dynamic objects as they are loaded.  The 
second -d prevents the application from forking, so it stays connected to the 
debugger.

}

\section{Debugging Dynamically Loaded Objects}

\leftindent{
Debugging is especially tricky with dynamically loaded objects.  The simplest 
approach is to copy the source files of andrew/atk/apps/ into a separate 
directory, add the dynamic objects to the lists in statload.c and build a 
runapp.  This runapp can then be debugged and the modules listed in statload.c 
will be statically loaded.  


To debug dynamically loaded objects, the ITC has a specially modified version 
of gdb which offers two new commands:


	set-rel <address> sets the relocation factor for subsequent add-file commands

	add-file <file path> loads the object file named


The appropriate address for set-rel is the one listed as the base in the 
listing generated with the -d switch to runapp.  It can also be found from the 
baseaddr field of entries in the ClassList table.  To aid in this, the xxxdog 
macros below can be used.



The .gdbinit file listed below assists in debugging in several ways:


The \bold{dir} commands specify the locations of source files for the most 
important parts of the toolkit.   Because of access to source, gdb can show 
the line associated with any point in the code.


Give the \bold{name }command immediately after printing a pointer to an 
object.  The name command traces through the object header to the field giving 
its name as a character string.  This gives a way of checking to see that a 
pointer points to an object of a sepcific type.



The XXXdog commands are another way to set the relocation address for loading 
symbols of a dynamic object.  \bold{lastdog} will print the name of the most 
recently loaded module.  \bold{prevdog} must be given after lastdog, prevdog, 
or nextdog; it prints the name of the precedingly loaded dynamic object. 
 \bold{nextdog} is similar to prevdog, but goes in the opposite direction in 
the list.  Finally, \bold{setdog} sets the relocation factor for the module 
whose name has just been printed by the last command, which must have been 
lastdog, prevdog, or nextdog.  \bold{firstdog} prints the name of the first 
object module, but this and its immediate nextdog successors have been 
statically loaded and do not need to have their symbol tables read separately.


After giving the setdog command, use `add-file \italic{filepath}` to load the 
symbol table.


.gdbinit file:

\leftindent{
define name

print ((struct basicobject *) $)->methods->info.name

end


define lastdog

print ClassList[ClassListEntries-1].className

print &$

end

define firstdog

print ClassList[0].className

print &$

end

define prevdog

print ((struct classload *)$ - 1).className

print &$

end

define nextdog

print ((struct classload *)$ + 1).className

print &$

end

define setdog

set-rel ((struct classload *)$).baseaddr

echo done.\\nNow use 'add-file <filename.dog>' to add the symbol table. \\n

end


dir /afs/andrew.cmu.edu/itc/src/andrew/overhead/class/lib

dir /afs/andrew.cmu.edu/itc/src/andrew/atk/support

dir /afs/andrew.cmu.edu/itc/src/andrew/atk/supportviews

dir /afs/andrew.cmu.edu/itc/src/andrew/atk/text

dir /afs/andrew.cmu.edu/itc/src/andrew/atk/basics/common

dir /afs/andrew.cmu.edu/itc/src/andrew/atk/frame

}
}

\section{Recent changes to CreateInset

}\leftindent{
Added gdb information.

Dec, 1989.  Finished revision to new Class system.

}
\section{Advice

}\leftindent{
Use `createinset` to begin work on a new inset.  Modify the contents as 
desired to give it the behavior you want.  In each file there are places to 
change to create your own inset.  These places are marked '$$$', either just 
before an entire section to change or at the end of a line to change.


}
\section{Related tools}  


Select (put a box around) one of the italicized names and choose "Get Help on 
Selected Word" from the pop-up menu to see the help file for:


\leftindent{\keyword{\italic{\helptopic{class}}} 

\keyword{\italic{\helptopic{Imakefile}}} 

\keyword{\italic{\helptopic{ATK programming}}}

}

\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1107,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,538380552}
