**********************************************************************
*								     *
*   file name: build_bde.hlp                                         *
*                                                                    *
*   Discription: This file is a help file for building bde system    *
*                on Unix. It assumes you have some knowledge of      *
*		 terms such as "CVS","bde", "chgen", "symtxt" etc.   *
*                It also assumes that you know how to use them once  *
*                you have excutable files                            *
*                                                                    *
*   Author: Haiyan Huang					     *
*                                                                    *
*   Date:   May 11, 1998                                             *
*                                                                    *
**********************************************************************
RJLRef: $PH/COOL-BDE/How2BuildBde_98s_hh.txt

0. How to build executables for bde:

   ( Assume you have a directory called .../bde/ that contains the files
     you checked out from bde's cvs reporsitory. This directory bde
     will be referred to as  .  )

   Complete the entire build for one type of host CPU at a time, 
   otherwise  your .o files will be invalid and recompile more than once. 
   the Makefiles are not smart enough to keep track of duplicate *.o files 
   and there is not enough disk space to duplicate source trees for 
   each hosttype. 

   The build procedure is as follows, starting 'from scratch':

   Makefiles are built using imkmf from the X library.
   It creates the X and Motif-dependent actions that bind bde to X-windows.

   [From MarkTorpey:
   How to build Makefiles and executables with imkmf, for one system
   at a time: 
	cs> cd ?/bde    	[this is your top level bde tree node]
	cs> make clean		[this will remove all old object files]
	cs> xmkmf -a		[this makes the Makefiles/dependencies]
	cs> make		[this actually makes bde]
   ]

   This will update the directory tree with the current sources and
   Makefiles, update the doc tree, and build the executable, whose
   full path name will be: 
 
	/bde/executable/${HOSTTYPE}/bde.

   where $HOSTTYPE is either vax or decstation.

   After that is done, you can repeat the whole process on another $HOSTTYPE:

	remus> cd bde
	remus> make clean
	remus> xmkmf -a
	remus> make

   This is because Imake will produce a (set of) Makefiles which
   "depends" on the current system.  It is  a system dependency tool.   
   A makefile produced by imake for CS will almost definiteLy not work on
   remus, and vice/versa.   Also, object files should always be removed
   when moving from one system from another (make clean).  This is
   because Make is sometimes brain-dead about checking for things like
   that. 

   Building bde on cs or remus should be no problem, 
   but a complete build takes a large amount of time (15-20 mins).
   [Bde needs more work for alpha hosts - it crashes immediately].

   Do not run make in directory  bde/src. The Imake is not set to
   allow that.  You have to be in your top-level bde directory. Its
   Makefile runs make in the src and pr_util subdirectories. 
   ]

   
  If everything is ok, you should find a file named bde in ./src/ ,
  this is the executable you made. 

  Most of the time you may not be able to build it at the first
  time. You need to check your machinetype as well as tp make sure
  that the various files that used by bde project are in the place
  that indicated by imakefiles. After years of development, they might
  be changed or moved to some place else. You need either change the
  Imakefile or put the files you need to the directory sepicified by
  the Imakefile. 


1. Heriarchy of BDE project:

   If you checked out the BDE source code from the reporsitory, (it's 
   /usr/proj3/case/95s523/95sbde/base/Master  when this document is
   finished.) Check if you have all these files and directories in 
   bde/:

	d      CVS
	f      Imakefile
	f      configure.h
	d      executables
	d      include
	d      lib
	d      pr_util
	d      schema
	d      src
	d      symtxt
 
  ( d stands for directory , f for file)

  if you don't have any of them you need to check out from the
  reporsitory ( using cvs checkout command);

  You may have more files in your bde directory. But only these above
  will be used in building excutable for bde.

  Take a look at the Imakefile first, you can learn the structure of bde
  from it.

   1.1 schema and pr_util directories:
   
    1.1.1 schema file:
   	
	BDE use chgen to generate utility functions according to the
	schema file in schema dirctory. The chgen generated *.c and .h
	files will be stored in pr_util directory. The schema name is
	very important. You need to be careful if you use the name
	other than 
		 94sbde_schema.sch
        If you want to change it, make sure that you also change the
	chgen to generate a header file other than
                  94sbde_schema.h
        in the pr_util directory and various places that using them. 	     
	These places are: 
		Imakefile
		configer.h

		pr_util/Imakefile
                include/ *.h

                src/Imakefile
		src/ *.cc
		symtxt/Imakefile

                symtxt/ *.h
		symtxt/ *.c

        The behavior of bde is hard to prodict even if you are an
	experenced programmer,. So be careful when you make these
	changes.

    1.1.2 files in pr_util
	
	The only file in pr_util needed to build bde is Imakefile. But
	you are likely to find:

		 94sbde_schema.h 
        and       pr_*.c

	These files will be automatically removed and replaced by
	those chgen generated files. So, if you found out that you
	need to change one of these files, you'd better go to chgen
	project and change the chgen source code ( or report
	to the chgen project team).    

	You can, of cause, change the files in pr_util after they are
	generated (after  0.2 >xmkmf -a) but before you call make to
	generate the excutables. Keep in mind that you will have to do
	so everytime you make any change for schema file.
 
  1.2 include directory
	
      The files in indlude directory are header files that will be
      used by bde code in ./src/ and ./symtxt/. Keep an eye on these
      files when you make any change in this directory.

  1.3 symtxt directory
  
      The files in symtxt directory are responsible for the compress
      the text field to tokens and symbols. They also use some
      utility functions in ./pr_util/ generated by the chgen for
      schema. 
 
      Take a look at the Imakefile in this directory and make sure
      that all the dependencies are correct. 

  1.4 src directory
  
      The files in src directory responsible for the functionalities
      for bde. Codes in this directory use utility routine defined in
      ./pr_util/ and ./symtxt/

      You also need to look at the Imakefile in this directory to make
      sure that all the dependencies are correct.


2. Current status and suggestion for improvements:

   2.0  The bde can only run on decstation. The efferts to make it
        runable on alpha machine still have no remarkable progress.
        If you are not trying to port the bde to alpha machine, build
	it on decstation like remus.

   2.1  The Imakefile will be better if you can change it to let the
        excutables be put to the ./executables/{$HOSTTYPE}/bde
   
   2.2  If possible, all header files should be put under ./include/.

   2.3  The dependencies in several places are not correct. For
        example, the .a file should depend on .c or .cc files not .o
        files so that whenever you changed the .c or .cc files, the .a
        file gets rebuild.


3. For more information about how to build bde, see:

    $CASE/95s523/95sbde/bde/how2buildbde.faq