source: trunk/third/wcl/README_BUILD @ 8837

SccsID: %Z% %M% %I% %E% %U%

Widget Creation Library Version 2.5 Build Instructions
-------------------------------------------------------


SNI AP Build Instructions
-------------------------

Simply execute the SniAp_Indigo or SniAp_SVR4 scripts as a user
with write permission to /CommonTools.  These scripts install the
libraries and resource interpreters in /CommonTools and in the
standard locations (/usr/bin and /usr/lib on SVR4, /usr/X11/bin and
/usr/X11/lib on Indigo).



Imakefiles and MakeByHand Makefiles
-----------------------------------

Both Imakefiles and hand-built (MakeByHand) Makefiles are provided.

If imake works on your machine, then USE IT!  The hand-built makefiles
work, but they are not any where near as convenient nor powerful.
Imakefiles are a far better way to go.  Bitch to your system
administrator and/or hardware/software vendor if imake does not work on
your machine.

If using Imake, all Wcl build and install paramters are pulled from a
file named Wc.tmpl.  There are many comments.  You probably only need
to edit the list of widgets, and the X release.

If you don't have Imake, then you should use the MakeByHand files.
MakeByHand is controlled by files named WcMake1.tmpl, WcMake2.tmpl,
WcMakeC.tmpl, and WcMakeL.tmpl.  You should never have to edit the
WcMakeC.tmpl or WcMakeL.tmpl files.  You probably can simply choose the
WcMake1* and WcMake2* which is closest to your platform, and make
symbolic links names WcMake1.tmpl and WcMake2.tmpl.

There are scripts named makeSun, makeSVR4, and so on which you can use
to make log files of the builds.  The file names are time stamps, which
means they can collide if the make goes REALLY fast (sometimes between
makeSun install and makeSun install.man).  You probably want to wait
a minute between the makes so the names do not collide.

        makeSun         BSD-ish system, including Sun and Indigo
        makeSV          SVR3 or SVR4
        makeSCO         SCO
        makeSNISVR4     SNI SVR4

There are three make targets you will probably use: World, install, and
install.man.  Also, you can clean after installing.

  -------------------------------------------------------------------------
  |  NOTE: OpenLook is not based on R5, so you must use MakeByHand, and   |
  |  not Imake, to build libWc, libXol, and Ori for OpenLook.  Wcl and    |
  |  the resource interpreters are Xt Intrinsics version dependent.  If   |
  |  you have different versions of libXt on your system, then you need   |
  |  different versions of libWc on your system.   This IS supported!     |
  -------------------------------------------------------------------------


Using Imake with X11R5 or X11R4
===============================


Quick Example: Sun with X11R5 and Motif
---------------------------------------
        % xmkmf
        % makeSun World
        % setenv LD_LIBRARY_PATH ./Xmp:./Xp:./Wc:$LD_LIBRARY_PATH
        % setenv PATH ./Ari:./Mri:$PATH
        % Ari -rf Ari/Demo
        % Mri -rf Mri/Demo


The Real Scoop
==============

The Wc.tmpl file is used to provide all imake parameters which are
important to building Wcl.  All you should ever need to do is change
the X11 release you have (about line 38) and the sets of widgets you
have (about line 52).

        % vi Wc.tmpl
        <change lines 38 and 52>

        NOTE: Even if you have R5, you probably do NOT have an R5
        compatible version of libXol.  Therefore, you very likely
        must leave HaveOpenLookWidgetSet set to NO.  More to come...

To build, do this (substitute makeSun with the appropriate make logging
script, or just use make):

        % xmkmf
        % makeSun World

Now test the distribution.  On SunOS and SVR4 machines, you need to
be certain you are using the newly built local libraries:

        % setenv LD_LIBRARY_PATH ./Xmp:./Xp:./Wc:$LD_LIBRARY_PATH
                -or-
        % LD_LIBRARY_PATH=./Xmp:./Xp:./Wc:$LD_LIBRARY_PATH
        % export LD_LIBRARY_PATH

Change the path, as the Demos will spawn more instances of Ari and/or
Mri, and start the resource interpreter demos for one or both of
Athena and Motif widget sets (whichever you have).

        % setenv PATH ./Ari:./Mri:$PATH
                -or-
        % PATH=./Ari:./Mri:$PATH

        % Ari -rf Ari/Demo
        % Mri -rf Mri/Demo

On R5, all the demos should work.  The demo interfaces may suggest that
there are problems with certain versions of Motif.  Also, the Template and
PerTem demos for Mri will NOT work correctly unless you have X11R5 patch
level 16 or later.

If anything seems strange, you can test the distribution in more detail
by compiling the Mri/Test program and using the Wc* resource files in
the Mri subdirectory.  By default, debug versions of the Wcl libraries
are built, and if you have Mri, then Mri/Test is built.  Assuming you
have Motif, you can do this:

        % cd Mri
        % dbx Test
        dbx> run -rf WcAll

There are targets useful for Saber-C (codecenter or objectcenter)
in the Makefile.  You can do this in objectcenter:

        % xobjectcenter&
        C++> make Saber
        C> run -rf WcAll

If everything works OK, then you can install.  You probably need to be
superuser to install.

        % su
        Password:
        # ./makeSun install
        # ./makeSun install.man


Sun with OpenWindows
--------------------

No imake with openwin for some reason, but the MakeByHand system works
well.  You should be able to use WcMake1.sun and WcMake2.sun without
any edits to create an OpenLook specific version of Wcl, and to create
Ori.

  NOTE: if you have X11R5 and OW, you MUST NOT create Ari by editing
  WcMake1.tmpl and uncommenting the WcATHENA define.  You MUST create
  Ari using imake and R5.  This means you need to make and install both
  an R5 version of Wcl for R5 Athena, AND an openwindows version of
  Wcl for Ori.

        % ln -s WcMake1.sun WcMake1.tmpl
        % ln -s WcMake2.sun WcMake2.tmpl
        % makeSun -f MakeByHand World

You can test the Ori open look resource interpreter like this:

        % setenv LD_LIBRARY_PATH ./Xop:./Wc:/usr/openwin/lib:$LD_LIBRARY_PATH
        % setenv PATH ./Ori:$PATH
        % Ori/Ori -rf Ori/Demo

NOTE: The Ori/ScrollingListDemo does not work, I am hoping that someone
will fix it, so I have left it in the distribution.  With some of the
Ori examples you might get warnings "OPEN LOOK Toolkit Warning in
application "Ori": Invalid XtNlabelJustify value: Using OL_LEFT as
default." which I suppose you can ignore.  This message simply points
out the limitations of some of the Xol string-to-resource converters
which will probably be improved over time.

If all the demos work OK otherwise, then install.  By default,
WcMake1.tmpl installs into /usr/openwin.  Edit the lines about 37 to
install where you like.  You probably need to be root to install.

        % su
        Password:
        # ./makeSun -f MakeByHand install
        # ./makeSun -f MakeByHand install.man



IRIX SVR3 with X11R4 and Motif 1.1.3
-----------------------------------
        % xmkmf
        % makeSun World

Test the distribution.  Ari for Athena and Mro for Motif should
have been built:

        % setenv PATH ./Ari:./Mri:$PATH
        % Ari -rf Ari/Demo
        % Mri -rf Mri/Demo

Everything should work except the PerTem and Template demos in
Mri, since these both require X11R5.

If everything seems to work, then install.  If you have a previous
version of Wcl on your SGI machine, first remove the include
directories.  You may also need to make /usr/man/mann for the man
pages.

        % su
        Password:
        # rm -rf /usr/include/X11/Wc
        # rm -rf /usr/include/X11/Xmp
        # rm -rf /usr/include/X11/Xp
        # ./makeSun install

<wait a minute so the log file names created by makeSun do not collide>

        # mkdir /usr/man/mann
        # chmod ugo+rx /usr/man/mann
        # ./makeSun install.man


SNI SVR4 with X11R5 and Motif
-----------------------------
        % xmkmf
        % makeSNISVR4 World
        % LD_LIBRARY_PATH=./Xmp:./Xp:./Wc:$LD_LIBRARY_PATH
        % export LD_LIBRARY_PATH
        % PATH=./Mri:./Ari:$PATH
        % export PATH
        % Ari -rf Ari/Demo
        % Mri -rf Mri/Demo
        % su
        Password:
        # ./makeSNISVR4 install
        # ./makeSNISVR4 install.man


SVR4 with X11R4 and Motif - static libraries
--------------------------------------------
        % ln -s WcMake1.svr4-a WcMake1.tmpl
        % ln -s WcMake2.svr4-a WcMake2.tmpl
        <edit WcMake1.tmpl line 24 if you do have Athena widgets>
        % makeSV -f MakeByHand World
        % PATH=./Mri:./Ari:$PATH
        % export PATH
        % Ari -rf Ari/Demo
        % Mri -rf Mri/Demo
        % su
        Password:
        # ./makeSV -f MakeByHand install
        # ./makeSV -f MakeByHand install.man



SVR4 with X11R4 and Motif - shared libraries
--------------------------------------------

        % ln -s WcMake1.svr4 WcMake1.tmpl
        % ln -s WcMake2.svr4 WcMake2.tmpl
        <edit WcMake1.tmpl line 24 if you do have Athena widgets>
        % makeSV -f MakeByHand World
        % LD_LIBRARY_PATH=./Xmp:./Xp:./Wc:$LD_LIBRARY_PATH
        % export LD_LIBRARY_PATH
        % PATH=./Mri:./Ari:$PATH
        % export PATH
        % Ari -rf Ari/Demo
        % Mri -rf Mri/Demo
        % su
        Password:
        # ./makeSV -f MakeByHand install
        # ./makeSV -f MakeByHand install.man



SCO ODT SVR3 with Motif 1.0
---------------------------

Sorry, but this is not very well supported.  You will need to edit
6 of the resource files in the Mri sub-directory, un-commenting
the resource specification line or lines following the comment lines:

        ! for old Motif 1.0

The files you must edit are Mri/Dialogs, Mri/Goodbye, Mri/Menubar,
Mri/Periodic, Mri/Wc, and Mri/WcAll.  It will only take a moment...

Then, build as follows:

        % mv WcMake1.sco WcMake1.tmpl
        % mv WcMake2.sco WcMake2.tmpl
        % makeSCO -f MakeByHand World
        % PATH=./Mri:./Ari:$PATH
        % export PATH
        % Mri -rf Mri/Demo
        % su
        Password:
        # ./makeSCO -f MakeByHand install
        # ./makeSCO -f MakeByHand install.man


Interactive 3.0.1
-----------------

This is supported only because someone (J.J.Bailey,
jjb@jagware.acco.com) sent me the WcMake1 and WcMake2 files for ISC.  I
cannot test this, but you should be able to build as follows:

        % rm WcMake1.tmpl WcMake2.tmpl
        % ln -s WcMake1.isc WcMake1.tmpl
        % ln -s WcMake2.isc WcMake2.tmpl
        % makeSCO -f MakeByHand World
        % PATH=./Mri:./Ari:$PATH
        % export PATH
        % Mri -rf Mri/Demo
        % su
        Password:
        # ./makeSCO -f MakeByHand install
        # ./makeSCO -f MakeByHand install.man

AIX
---

Fairly smooth.  I've only got one AIX machine...

        % rm WcMake1.tmpl WcMake2.tmpl
        % ln -s WcMake1.aix WcMake1.tmpl
        % ln -s WcMake2.aix WcMake2.tmpl
        % makeSV -f MakeByHand World
        % PATH=./Mri:$PATH
        % export PATH
        % Mri -rf Mri/Demo
        % su
        Password:
        # ./makeSV -f MakeByHand install
        # ./makeSV -f MakeByHand install.man


        
ESIX
----

The Imake system has some problems on some ESIX platforms.  First,
try imake.  If you have problems, look at the file ESIX for suggested
fixes to the Makefiles generated by the ESIX imake.


POTENTIAL PROBLEMS
------------------

If using SunOS 4.1.2 and X11R4 (fixes 1-18), then you may have
a problem linking Ari:

        ld: Undefined symbol
        _get_wmShellWidgetClass
        _get_applicationShellWidgetClass

A solution is to statically link libXmu.a, for example, add:

        XMULIB = /usr/lib/libXmu.a

to your Wc.tmpl.

If you get an undefined symbol error for XtSetDefaultFilePredicate,
then you somehow have -DXTRACEFILEHACKS passed to cc, and you don't
have a specially hacked Xt.  Remove this flag.

If you get undefined symbol errors for __XtFree, __XtMalloc, __XtCalloc
then you somehow have -DXTTRACEMEMORY passed to cc, and you don't have
a specially built Xt.  Note that if you have -DXTTRACEMEMORY set when
you build Xt, you really should build all libraries on top of Xt
(widget libraries, Wcl, the client) also using -DXTTRACEMEMORY.  Hardly
anyone does this, but I think it is worthwhile for debugging.

You never NEED to build the Stuff directory (it is never installed).
The Mri/Test resource files can make use of the Stuff library for
testing dynamic linking of callbacks.  Comment out the references to
Stuff at about line 289 in Wc.tmpl and about line 72 in WcMake1.tmpl
to disable doing anything with Stuff.




Passing Wcl on to others
------------------------

As mentioned in the Wcl copyright (see the COPY.h include file) the entire
Wcl distribution can be given to others.  In order to make this easy, the
hand-built Makefile has targets for making compressed tarfiles:

        % make -f MakeByHand tar.Z

   _____________________________________________________________________
  |  David E. Smyth                         David.E.Smyth@jpl.nasa.gov  |_
  |_____________________________________________________________________| |
  |  Project: Mars Pathfinder -- Low Cost Lander with "Rocky IV" Rover  | |
  |  Team:    Flight Software -- Object-Oriented Software for Mars      | |
  |_____________________________________________________________________| |
  |  Voice:    (818) 393-7944                                           | |
  |  FAX:      (818) 393-0530                                           | |
  |  Office:   Space Flight Operations Facility 230/207a                | |
  |  Snail:    JPL, MS 230-200, 4800 Oak Grove Dr., Pasadena, CA 91109  | |
  |_____________________________________________________________________| |
    |_____________________________________________________________________|