Download devPad 0.70 devPad Installation and User`s Guide

devPad 0.70
devPad Installation and User's Guide
====================================
Copyright(c) Martin Lafaix, 1997-1998. All rights reserved.
[Many generic parts of this document were shamelessly snarfed from
NetRexx's Installation and User's Guide. Typos and grammar errors are
all mine, though... :-) ]
Introduction
""""""""""""
This document is the "User's Guide" for devPad.
devPad is a development environment for NetRexx and Java. It is
completely written in NetRexx, and so it is not tied to a particular
platform. All you need is a system that implements a Java Virtual
Machine.
This document covers:
o Unpacking the devPad package
o Installing the devPad package -- documentation and samples
o Installing the devPad executables (for any Java platform):
o How to install the devPad environment
o Problem solving
o Special note for JDK 1.1 users
o Using the devPad environment
o Current restrictions, _etc._
The devPad documentation and software are distributed free of charge
under the conditions explained below. If you download or use a devPad
package you agree to the terms in the _License Agreement_ included in
the package as the file license.txt.
For details of the devPad environment, and the latest news, please see
the devPad documentation included with this package or available on the
World Wide Web, for example at: http://wwwi3s.unice.fr/~lafaix/devPad/
Martin Lafaix
Unpacking the devPad package
""""""""""""""""""""""""""""
The devPad package is shipped in two forms, identified by a suffix
following the name:
o .zip format -- commonly used on OS/2 and other operating systems for
the IBM PC
o .tar.gz format -- (tape archive plus gzip) commonly used on Unix
systems.
You probably know how to handle these, but a word of caution: the
packages contain directory structures, and files with 'long names'
(that is, not of 8.3 maximum length names) which are case-sensitive.
Many utilities, including some versions of UNZIP and TAR, can lose
case information, truncate names, or fail to restore directories.
--- Unpacking .zip files --The most common packages for 'unzipping' these are Info-ZIP and PKZIP:
Here are some tips:
o Ensure that you are unzipping to a disk that supports long file
names (for example, an HPFS disk or equivalent on OS/2 or Windows).
o Info-ZIP: use version 5.12 (August 1994) or later.
unzipping devPad.zip is simply
The syntax for
unzip devPad
which should create the files and directory structure directly.
Please see later in this document for complete installation
instructions.
o PKZIP: use a version that supports long file names.
unzipping devPad.zip is
The syntax for
pkunzip -d devPad
which should create the files and directory structure directly. The
'-d' flag indicates that directory structure should be preserved.
--- Unpacking .tar.gz files --You need an up-to-date version of two programs: 'tar' and 'gzip';
these are available for most operating systems. Here are some tips:
o Ensure that you are unpacking to a disk that supports long file
names (for example, any Unix disk, or an HPFS disk or equivalent on
OS/2 or Windows).
o Ensure that the version of tar that you use preserves case in names.
If all the files created by tar have all-lowercase names, you need a
new version of tar.
The process of unpacking the file takes two steps:
1. Uncompress the file, using gunzip (this may be called
simply 'gzip' on some systems). The syntax for uncompressing
NetRexx.tar.gz is probably one of:
gunzip devPad.tar.gz
gzip -d devPad.tar.gz
(the '-d' means decompress, and may be optional).
replace the file with one called devPad.tar
This should
2. Unpack the files and directories from the .tar file.
for this is
The syntax
tar -xvf devPad.tar
This should create the files and directories from the package,
displaying the name of each as it is unpacked. You may see error
messages where directories already exist; these can be ignored.
After unpacking the files, the .tar file can be erased.
Installation procedure - online documentation and samples
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The devPad package (devPad.zip, or devPad.tar.gz) contains the devPad
online documentation, together with samples and examples, and the
packages of executables.
1. Copy the package file to the root directory of your choice,
preserving the original name.
2. With your chosen directory as your current directory, unpack the
package, following the instructions in 'Unpacking the devPad
package' above.
This should add the directory 'devPad' to your chosen directory,
containing the documentation and samples for devPad, along with
the packages of executables.
The online documentation comes in two forms: plain ASCII (files with
extension '.doc'), and World Wide Web hypertext format (files with
extension '.html', '.gif', etc.). To view the hypertext version, start
your browser at the file "devPad.html". For example, if you are using
the IBM Web Explorer then the command
explore devPad.html
(executed when the documentation directory is the current directory)
should show the devPad front page.
Included in the documentation collection are some examples and
samples (A simple devPad, etc.). To run any of these, you must have
the Java and NetRexx toolkit and runtime environment installed.
Installation of devPad Executables
""""""""""""""""""""""""""""""""""
To install and use the devPad packages, you must have already installed
the Java Development Kit (JDK) and NetRexx runtime and toolkit. For
more information on these:
o For OS/2 and AIX and other IBM operating systems, see the _IBM
Centre for Java Technology_ page at:
http://ncc.hursley.ibm.com/javainfo/hurindex.html
o For other operating systems, see the _Sun Microsystems Java_ page
at http://www.javasoft.com, or other suppliers of Java toolkits.
o For NetRexx, see the _NetRexx_ page at:
http://www2.hursley.ibm.com/netrexx/
Installation of the devPad environment
""""""""""""""""""""""""""""""""""""""
Here's how to install the devPad environment and runtime classes:
1. Copy the 'dpenv.zip' or 'dpenv.tar.gz' file from the devPad
documentation directory to the Java home directory, using the
original name. The name of the Java home directory will vary
depending on the operating system you are using. Some
possibilities are:
/java
/jdk1.1/java
\javaos2
\jdk1.1\java
It will contain directories such as 'bin' and 'lib'.
[Note: if your Java home directory is on a CD-ROM, or otherwise
inaccessible, you'll need to choose a different directory and set
up a CLASSPATH environment variable that points to it. Consult
your Java toolkit documentation for details on how to do this.
You'll also need to set the devPad home directory -- see below.]
2. With the Java home directory as your current directory, unpack the
package, following the instructions in "Unpacking the devPad
package" above.
This should add the .zip file for the devPad environment classes
(devPad.zip) and the environment's preferences and runtime
documentation files (devPad.icons/*, devPad.properties, ISOlat1.ent
and nodoc.html) to the Java 'lib' directory.
In addition, some sample scripts should have
been added to the Java 'bin' directory:
devPad.cmd -- the devPad environment command in Rexx
dp.cmd
-- shorter name for devPad.cmd
The .cmd files are simple batch scripts for making it easier to use
the compiler. You don't have to use these, but they save some
typing. They should require little modification to run under
your platform.
3. Check that the names are correct in the 'lib' directory: there
should be a directory called 'devPad.icons' and files called
'devPad.properties', 'ISOlat1.ent' and 'nodoc.html'; if the name is
all in lowercase, or the word 'icons', 'properties' or 'html' is
truncated, the package has not been unpacked correctly (see
"Unpacking the devPad package").
4. For Java to be able to find the devPad classes, you must update
the CLASSPATH environment variable by adding the full path and name
of the devPad.zip file to the CLASSPATH setting. There will
often already be a CLASSPATH variable set, including a path to the
standard Java classes.zip file. Specify or add the full path
(disk, directories, and file specification) for devPad.zip,
making sure that the case of every letter is exactly right (Java is
very case-sensitive). For example, the full path might be something
like:
e:\javaos2\lib\devPad.zip
The procedure for setting the CLASSPATH variable depends on your
operating system (and there may be more than one way). Here are
some examples:
o In OS/2 or
(for OS/2)
changing.
might look
Windows, use a SET CLASSPATH= command in CONFIG.SYS
or in AUTOEXEC.BAT (for Windows) and re-boot after
In both cases the command syntax is the same, and
like this:
set classpath=.;f:\javaos2\lib\devPad.zip
In this example, the first segment of the value (before the
semicolon) lets classes in the current directory be found, and
the second segment includes the classes needed by devPad.
Both environments normally include the standard Java classes
automatically.
o For Unix (Korn shell or Bourne shell), use:
CLASSPATH=<newdir>:$CLASSPATH
export CLASSPATH
and changes for re-boot or opening of a new window should be
placed in your .login (Bourne) or .profile (Korn) file
o For Unix (C shell), use:
setenv CLASSPATH <newdir>:$CLASSPATH
and changes for re-boot or opening of a new window should be
placed in your .cshrc file
If you are unsure of how to do this, check the documentation you
have for installing the Java toolkit.
--- Checking your installation is correct --To check installation, change directory to the devPad documentation
directory, then (being very careful to get the case of letters correct):
o
Enter the command
java devPad.devPadMain Welcome.pad
This should starts the devPad environment, and open the Welcome
workspace.
With the sample scripts provided (devPad.cmd), or the equivalent in the
scripting language of your choice, the steps above can be combined into
a simple single command:
devPad Welcome.pad
This package also includes a trivial 'dp.cmd' file that simply passes on
its arguments to devPad; 'dp' is just a shorter name that saves
keystrokes, so for the last example you could type:
dp Welcome.pad
Note that scripts may be case-sensitive; unless running the OS/2 Rexx
script, you will probably have to spell the name of the program exactly
as it appears in the filename.
--- The devPad Home directory --If you need to put the devPad.properties and runtime documentation files
into a directory other than the 'lib' directory below the Java home
directory, then you can set an alternative directory path that devPad
will use to find the messages file.
This alternative directory is called the devPad home directory and may
be set using the -D option on the java command that invokes the devPad
environment. For example (perhaps for an OS/2 or Windows system):
java -Ddevpad.home=f:\dphome devPad.devPadMain Welcome.pad
which sets the directory path 'f:\dphome' as the devPad home directory.
With this setting, devPad would look for the properties file as:
f:\dphome\lib\devPad.properties
In other words, devPad expects its properties and runtime documentation
files to be in the 'lib' directory below the devPad home directory, and
the default devPad home directory is the Java home directory.
If you are using the devPad.cmd on OS/2 to invoke the compiler, then
this -D option will be set up automatically if the path is set as the
value of an environment variable called DEVPAD_HOME.
Problems?
"""""""""
If the 'Welcome.pad' example doesn't work, one of the following problems
may be the cause:
o A "Can't find class devPad.devPadMain..." message probably means
that the devPad.zip file has not been specified in your CLASSPATH
setting. This is the setting that Java uses to find classes for
execution; please refer to your Java installation instructions for
information on setting the CLASSPATH.
o You didn't install on a file system that supports long file
names (for example, on OS/2 or Windows you should use an HPFS disk
or equivalent). Like most Java applications, devPad uses long file
names.
o You have a down-level Unzip or Tar program. Check that the
file 'devPad.properties', with just one capital letter and
neither part of the name truncated, exists in the subdirectory
'lib' below the Java home directory.
o You have only the Java runtime installed, and not the toolkit. If
the toolkit is installed, you should have a program called javac
on your computer.
o A "Exception in thread 'main' java.lang.NoClassDefFoundError:
netrexx/lang/Rexx..." message probably means that you didn't
install the NetRexx toolkit and/or runtime.
o You have a down-level version of Java installed. devPad will run
on Java versions 1.0.1, 1.0.2 (and probably later versions).
You can check the version of Java you have installed using the
command 'java -version'.
o You are getting OutOfMemoryExceptions. When browsing large
hierarchies, it is possible to exceed the default maximum memory
size available (16Mb). To overcome this limit, define a bigger heap
(the procedure to achieve that is environment-depent, but you
usually have to add a '-mx_nn_m' statement on the java invocation
line, for example 'java -mx32m devPad.devPadMain foo.pad').
Special note for JDK 1.1 users
""""""""""""""""""""""""""""""
While this release of devPad is a Java v1.0 application, it also works
with Java v1.1, with the following limitations:
o Compressed JARs are not recognized and hence may crash
class/package browsers ;
o The class and package browsers display inner classes in their
mangled form ;
o Deprecated methods are not distinguished from normal methods ;
o Due to the size increase in the provided packages, the default
maximum heap size (16Mb) may be too small. If you receive
OutOfMemoryExceptions exceptions, increase it. Similarily,
specifying a bigger default heap size (1Mb by default) helps initial
performances ;
The recommended invocation line is hence:
java -ms24m -mx32m devPad.devPadMain xxx.pad
o Due to a change in scrollbar handling, the end of some areas may be
inaccessible (HTML areas, DevPad areas and Hierarchy areas).
o The cursor keys (Up/Left/Down/Right arrows and PageUp/PageDown)
don't work in HTML, Hierarchy and DevPad areas (but they do work in
Editable areas :-)
--- Specific implementation notes --Sun's JDK 1.1.5 on NT
List controls are incredibly slow in this release. Allows up to 3
minutes to fill the class list for the java.* hierarchy (667 classes)
on a Pentium 133. (On other plateforms, say, OS/2, it takes less than
10 second.)
[Specifying '*' in the filter field the the aforementionned package
browser requires 1'30''.]
When exiting a non-saved devPad, the application locks when you select
either the 'Save then quit' or the 'Quit without saving' buttons in the
requester. If 'Save then quit' was selected, the pad is indeed saved.
You can then safely kill the application from the command window, by
pressing Ctrl+C.
[This behavior does not occur if you select 'Save pad' in the 'Pad'
menu before exiting.]
IBM's JDK 1.1.4 on OS/2
The safest way to use devPad with this implementation is to disable the
Just In Time compiler (by defining the JAVA_COMPILER environment
variable).
[You can enable the JIT compiler, but then don't try to resize the
window when the Layout view is displayed (devPad will lock).
Similarily, you will notice some unexpected errors. As this behavior
is not reproductible when the JIT is disabled, it's quite probably
bugs in the JIT code.]
The popup menu window background is not painted.
Using the devPad environment
""""""""""""""""""""""""""""
The installation instructions for the devPad environment describe how to
use the package you installed to open a simple devPad workarea. This
section explains more of the options available to you.
--- Invoking the environment as a command --The environment is a Java program (class) which is called
devPad.devPadMain (devPadMain for short). This can be invoked using the
Java interpreter, for example, by the command:
java devPad.devPadMain
or by using a system-specific command (such as 'devPad' or 'dp'). In
either case, the environment invocation is followed by one workarea
name (the workarea to be opened).
So, for example, to open 'Welcome.pad', you can use any of:
java devPad.devPadMain Welcome.pad
devPad Welcome.pad
dp Welcome.pad
(the first one should always work, the last two require that the
system-specific command be available).
If the given parameter does not represent an existing workarea, a new
empty one will be created. (It is recommended that workareas have a
'.pad' extension, but it is not enforced in any way.)
During the existence of the workarea, classes and other temporary files
are stored in the current directory.
When a workarea is in use, many commands produce output to the standard
output stream (for example, compilation results, etc.). It is so
recommended to open the Java console when starting the devPad
environment. So, for example and if you use OS/2, you can enter:
start javapm -cons devPad.devPadMain Welcome.pad
--- Invoking devPad tools as a separate commands --Some parts of the devPad package can be called from a command line or
from other Java programs. These commands are:
o java devPad.dumpClass [-p] classname [classname...]
this command mimics the javap command, but also reports signaled
exceptions (and the result uses a NetRexx syntax).
o java devPad.ClassBrowser packagename
this command opens a package browser.
o java devPad.ZipFile zipfile
this command lists the content of a zip file.
[The documentation for all public methods defined in the devPad package
is not completed yet. When done, it will be made publicly available.]
Current restrictions
""""""""""""""""""""
The devPad environment is not yet functionally complete. As of this
version there are still a number of restrictions, listed below.
Please note that the presence of an item in this section is not a
commitment to remove a restriction in some future update; devPad
enhancements are dependent on on-going research, your feedback, and
available resources. You should treat this list as a 'wish-list' (and
please send in your wishes).
o There's no way for the package browser to refresh its content. If a
class changes, it is not taken into account.
o The package browser only offers a "Class browser" and "Hierarchy"
view. A "Member browser" view is in the work.
o In the package browser, there's no way to locate a specific member's
implementor or caller.
o The "Icons" and "Book" views are not yet available view in a devPad
workarea.
o No contextual help is available.
o Many options are grayed out in the devPad menu bar.
o The HTML parser is very slow, and does not yet recognize CSS1.
o The text editor is too simple (no highlighting, _etc._)
o The look-and-feel is quite rough.
o [...]