CMVC 2.3.1 Source Code

How to setup a CMVC Build user id and
to store the source code into a CMVC family

*** Document data

Author:		Angel Rivera
			IBM CMVC Support Team
			IBM Software Solutions
			Research Triangle Park, North Carolina, USA.

Date last updated:	31-Oct-2001

Location of this document:

a) External FTP site for CMVC:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/SetupSourceCode.rtf
b) Host "angel.raleigh.ibm.com"
	d:\work\cmvc\extended support\SetupSourceCode.rtf
c) See the corresponding entry in the VisualAge TeamConnection Tips Database.

*** Purpose of this document

The purpose of this document is to describe how to setup a CMVC Build user id and to store the source code of CMVC 2.3.1 into a CMVC family.

*** Select a host where the CMVC source code will be built

In this note, it is assumed that the CMVC source code will reside in a CMVC family that is located in a host that comply with the hardware and software requirements for CMVC. Let's assume that the name of the host is "host-1".

You have to ensure to have around 500 MB available in the home directory of the CMVC family, such as /home/cmvcsrc

In addition, this host will have a CMVC Build user id, (/home/build), which will extract the source code from the CMVC family and proceed to build and package the compiled code. You have to ensure to have around 1 GB available in the home directory of the CMVC build user id in order to extract the code, build it and package it. This amount is enough to have a couple of directories for different level versions of the CMVC source code and the corresponding compiled code.

*** Install the proper DBMS with the corresponding SDK and/or development components

The following technical reports describe how to perform the installation and configuration of the appropriate DBMS in order to be used with a CMVC family.

- "CMVC frequently asked questions: how to perform typical operations with Sybase 11.9.2"
  The URLs are:
   a) PDF version, needs Acrobat Reader:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/trcmfsyb.pdf
   b) Plain text version:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/trcmfsyb.txt

- "CMVC frequently asked questions: how to perform typical operations with Oracle 7.3.4"
  The URLs are:
   a) PDF version, needs Acrobat Reader:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/trcmfora.pdf
   b) Plain text version:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/trcmfora.txt

*** Install the latest CMVC server and client code

As root, you need to install both the CMVC server and client in the host.

*** Create a CMVC Family (where the source code will be stored)

Now that the DBMS and the CMVC executable code have been installed, then you can proceed to create a family where the CMVC source code will be stored later on. In this document this family will be referred to as "cmvcsrc" (for CMVC source code).

You can use the following profile as the basis for the .profile of the family (choose the appropriate one):
	/usr/lpp/cmvc/install/profile.sybase
	/usr/lpp/cmvc/install/profile.oracle

Start the family, such as:
	cmvcd $LOGNAME 2

*** Create a Build user id (to compile the CMVC source code)

- As root, insert the CD-ROM with the CMVC source code and mount the CD-ROM. Let’s assume that the mount point is: /cdrom

- As root (in "host-1") you need to create a group id and a user id for the CMVC Build user.
In our site we use the following characteristics for this user id:

gid=222(syscmvca)
uid=210(build)
HOME=/home/build

- Login as "build" and make a backup copy of the .profile (because it will be overwritten in a later step, and you may want to have the original backup in case that you need it).
	cp -p .profile .profile.backup

- Create the file tree structure for the CMVC code:

cd $HOME
mkdir cmvc231     # CMVC 2.3.1 source code and utilities
mkdir bin         # for miscellaneous utilities
mkdir tardir      # temporary directory for packaging
mkdir lpptools    # packaging utilities for AIX installp/smit
mkdir pubs        # all CMVC manuals and technical reports

*** Expand the tar files with the source code and copy other files

- As user "build", expand the tar files from the CD-ROM (assuming that it was mounted in /cdrom):

cd $HOME
# The result of the untar will be a directory $HOME/pubs with
# the following subdirectories:
# $HOME/pubs/pdf  -> All CMVC manuals in PDF format
# $HOME/pubs/html -> The Quick Commands Reference guide
# $HOME/pubs/technical-reports -> All technical reports for CMVC
tar -xvf /cdrom/pubs.tar

cd $HOME/cmvc231

# The result of the untar will be a directory $HOME/cmvc231/cs2316
tar -xvf /cdrom/cs2316.tar

# The result of the untar will be a directory $HOME/cmvc231/gui2316
tar -xvf /cdrom/gui2316.tar

# The result of the untar will be a directory $HOME/cmvc231/inst2316
tar -xvf /cdrom/inst2316.tar

# The result of the untar will be a directory $HOME/cmvc231/tools2316
# This is the first extract, in order to create these files into the family.
mkdir $HOME/cmvc231/tools2316
cd    $HOME/cmvc231/tools2316
tar -xvf /cdrom/tools2316.tar

# This is the second extract, in order to have the tools
# in the proper directories for actual usage.

cd $HOME
# The result of the untar will be several directories under $HOME
# and files such as .profile
tar -xvf /cdrom/tools2316.tar

## Only for AIX
cd $HOME
# The result of the untar will be a directory $HOME/lpptools
tar -xvf /cdrom/lpptools.tar

- As user "build", copy the map files and scripts from the CD-ROM:

cd $HOME/cmvc231
cp /cdrom/*.mapFile .
cp /cdrom/importFiles .
cp /cdrom/*.ksh .

- Restore the proper version of the .profile for "build". The untar of tools2316 overwrote the .profile, but this is a very large file that makes sense only in the IBM site. A shorter version is provided in the CD-ROM and it is the one that you can use (you will need to customize it).

cd $HOME
mv .profile .profile.build.old 
cp /cdrom/profile.build .profile     

- Customize the new .profile. Please contact IBM CMVC support for assistance. Some specific things to be changed are:

  - For Solaris 2.x:
    - In the big case statement "case `$HN_CMD` in " search for "solaris2" and customize the complete section to reflect the values in your site. You will need to replace "solaris2" for the short name of the host.

  - For AIX 4.x:
    - In the big case statement "case `$HN_CMD` in " search for "aix4" and customize the complete section to reflect the values in your site. You will need to replace "aix4" for the short name of the host.

- Logoff and log in back to activate the new .profile.

*** Create User, Components and Releases in the CMVC family

- Login to the user id that is the CMVC family administrator (CMVC superuser).

- The script “setupSource.ksh” does all the tasks in this section. Please review it to understand the tasks that performed, such as:

•	Add a User named "build" and a corresponding Host list entry for "host-1".
•	Add an Access entry of "builder" for the user "build", for the component "root".
•	Create a component "cmvc" with parent component "root" and assign the user "build" as the component owner. This component will be the top of the hierarchy of the CMVC source. It uses the "default" process which has the subprocesses: dsrFeature, verifyDefect and verifyFeature.
•	Create the following 4 components and assign the user "build" as the component owner. The parent component is "cmvc" and the process is "default".
o	cmvcCS: to store the source code for the Client (line commands) and Server
o	cmvcGUI: to store the source code for the GUI
o	cmvcInst: to store the installation utilities
o	cmvcTools: to store miscellaneous tools.
•	Add an Access entry of "componentlead" for the user "build" for each of the above 5 new components. In that way, the user "build" could give proper access to other team members.
•	Create the following 4 releases under the appropriate component, using user "build" as the release owner. The recommended process is "track_level" which has the following subprocesses: fix, track and level. The idea behind this process is to use a level in order to have a baseline of the source code.
o	cs231: to store the source code for the Client (line commands) and Server
o	gui231: to store the source code for the GUI
o	inst231: to store the installation utilities
o	tools231: to store miscellaneous tools.

- WARNING: You need to customize this script; specifically, you need to provide the host name from where the user "build" will be accessing the CMVC family.

- Execute the script.
	setupSource.ksh

*** Store the files into the CMVC family

- Login into the user id "build", in order to work as the CMVC Build user id.

- Ensure that the environment variables are properly set, such as (they need to be appropriate to your setting):

export CMVC_BECOME=build
export CMVC_FAMILY=cmtc8db2@tcaix08@3440

- The script “storeSource.ksh” does all the tasks in this section. Please review it to understand the tasks that performed, such as:

-	Open a Feature and the corresponding tracks to checkin the source code. In this example, the feature name is "source1" which is specified in the following variable:
o	export FEATURE_NAME="source1"
-	Load the source code for the Client Server. By default the files will be text, unless CMVC cannot handle the text, in which case the file will be created as binary.
o	export CMVC_RELEASE=cs231
o	export CMVC_COMPONENT=cmvcCS
o	from directory $HOME/cmvc231/cs2316 using mapFile cs2316.mapFile
o	Take a look at the most recent /tmp/outfile* to see the commands that were executed.
o	Take a look at the most recent /tmp/badfile* to see if there were any commands that failed.
-	Load the source code for the GUI:
o	export CMVC_RELEASE=gui231
o	export CMVC_COMPONENT=cmvcGUI
o	from directory $HOME/cmvc231/gui2316 using mapFile gui2316.mapFile
-	Load the source code for the Installation utilities:
o	export CMVC_RELEASE=inst231
o	export CMVC_COMPONENT=cmvcInst
o	from directory $HOME/cmvc231/inst2316 using mapFile inst2316.mapFile
-	Load the source code for the Miscellaneous tools:
o	export CMVC_RELEASE=tools231
o	export CMVC_COMPONENT=cmvcTools
o	from directory $HOME/cmvc231/tools2316 using mapFile tools2316.mapFile

- Execute the script.
	storeSource.ksh

*** Perform quick checkup; if fine, commit the changes

- Use the CMVC GUI and show all the files for the releases just populated in the CMVC Family. The following is the count of files in order to provide a reference point.

cs231:		875 files
gui231:	162 files
inst231:	252 files
tools231:	139 files

- If the above numbers match the ones in your system, then you can proceed to commit the corresponding levels.

REASONING: It is very important that the first committed level in the release in your CMVC family SHOULD be AS-IS, as we provided it. Please, DO NOT try to add, delete or modify any files; you can do that in subsequent levels, but NOT in the first one.
The idea is that you could always count in extracting the first level to see EXACTLY what was sent to you by us.

- The script “storeSource.ksh” does all the tasks in this section. Please review it to understand the tasks that performed, such as:

-	Create the level “1” for each release.                                                                              
-	Integrate the tracks by completing the fix records.
-	Add the level members.
-	Commit and complete the levels.
-	Accept the verification records.

- Execute the script.
	commitSource.ksh

*** Cleanup the $HOME/cmvc231 directories and extract the releases

NOTE: The release "tools231" is not extracted in this section, because it will overwrite the .profile file. You could try to extract the release, but be aware of the overwriting.

- As the CMVC build user id, cleanup the $HOME/cmvc231 directories. These directories were needed to have a staging area in order to check-in initially the source code files into CMVC. However, the directory names are too specific, and the recommendation is to delete these names and create new directory with names that are more generic.

cd $HOME/cmvc231
rm -fr cs2316
rm -fr gui2316
rm -fr inst2316
rm -fr tools2316

- Create directories with names that are more generic. These are the names that will be used in the instructions on how to build the code.

cd $HOME/cmvc231
mkdir cs
mkdir gui
mkdir inst

- Extract the CMVC releases. You need to customize the following statements. Also, you need to give the proper directory permissions for the extract action, which by default uses NFS. The statements need to be executed in a single line. You could also use the GUI.

Level  -extract 1 -release cs231   -full  -node host-1 -root /home/build/cmvc231/cs   -uid 210 -gid 222 -dmask 777 -verbose

Level  -extract 1 -release gui231  -full  -node host-1 -root /home/build/cmvc231/gui  -uid 210 -gid 222 -dmask 777 -verbose

Level  -extract 1 -release inst231 -full  -node host-1 -root /home/build/cmvc231/inst -uid 210 -gid 222 -dmask 777 -verbose

*** What is next?

Now that you have stored the CMVC source code in the CMVC family and extracted successfully the source code into the CMVC build user id, the next task is to test that you can build the source code.

See the document “BuildSourceCode.rtf”: 
“CMVC 2.3.1 Source Code: Simplified instructions on how to build the source code of CMVC and package the compiled code”

*** end ***