HOW TO BUILD AND PACKAGE THE CMVC SERVER/CLIENT FOR UNIX Document Number TR 29.2269 Angel Rivera, Lee Perlov, Gurpreet Koura TeamConnection/CMVC Development IBM Software Solutions Research Triangle Park, North Carolina Copyright (C) 1997 IBM Corp. All rights reserved. ii Building CMVC for UNIX ABSTRACT The purpose of this technical report is to provide a real example of the use of CMVC for developing, maintaining, building and packaging the CMVC Server and Client for UNIX, which encompasses several operating systems and database management systems. This example illustrates the complexity associated with the develop- ment of applications in heterogeneous environments. ITIRC KEYWORDS o CMVC o UNIX o Building o Packaging ABSTRACT iii iv Building CMVC for UNIX ABOUT THE AUTHORS ANGEL RIVERA Mr. Rivera is a Staff Programmer and team lead for the CMVC development. He joined IBM in 1989 and since then has worked in the development and support of library systems. Mr. Rivera has an M.S. in Electrical Engineering from The Univer- sity of Texas at Austin, and B.S. in Electronic Systems Engi- neering from the Instituto Tecnologico y de Estudios Superiores de Monterrey, Mexico. LEE R. PERLOV Mr. Perlov is a Staff Programmer in the TeamConnection/CMVC development group. He started working for IBM in 1985 in Gaithersburg, Md, working in the Federal Systems Division on various projects for the United States intelligence community. He then moved to RTP to work on library development and support. Mr. Perlov received a B.S.Acc degree in Accounting from the Uni- versity of Florida in 1983. He also completed two years of grad- uate work in the Department of Computer Science at the University of Florida. GURPREET KOURA Mrs. Koura is a Senior Associate Programmer and customer service contact for CMVC and TeamConnection. She joined IBM in 1996. Mrs. Koura received a B.Sc. in Computer Sciences from North Carolina Central University in 1993. ABOUT THE AUTHORS v vi Building CMVC for UNIX CONTENTS ABSTRACT . . . . . . . . . . . . . . . . . . . . . . . . . III ITIRC KEYWORDS . . . . . . . . . . . . . . . . . . . . . iii ABOUT THE AUTHORS . . . . . . . . . . . . . . . . . . . . . . V Angel Rivera . . . . . . . . . . . . . . . . . . . . . . . v Lee R. Perlov . . . . . . . . . . . . . . . . . . . . . . . v Gurpreet Koura . . . . . . . . . . . . . . . . . . . . . . v FIGURES . . . . . . . . . . . . . . . . . . . . . . . . . . . X 1.0 BUILDING AND PACKAGING CMVC FOR UNIX . . . . . . . . . . 1 1.1 Disclaimer . . . . . . . . . . . . . . . . . . . . . . 2 2.0 CHALLENGES RELATED WITH HETEROGENEOUS ENVIRONMENTS . . . 3 2.1 Maintaining all needed combinations of hardware and software . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Role of 'build' userid and exported directory . . . . 3 2.2.2 Standardize the location of ksh to /usr/bin/ksh . . 5 2.2.3 Identifying the operating system . . . . . . . . . 5 2.2.4 Shared .profile . . . . . . . . . . . . . . . . . . 7 2.3 Using a bulletin to communicate news (message-of-the-day) . . . . . . . . . . . . . . . . . . . 7 3.0 OVERALL PROCESS WITH CMVC . . . . . . . . . . . . . . . 9 3.1 Families, Components and Releases . . . . . . . . . . 9 3.2 Process model . . . . . . . . . . . . . . . . . . . 10 3.3 Project lead creates components and releases . . . . 11 3.4 Handling defects and features . . . . . . . . . . . 11 3.5 Developers work with files using tracks (Code and Unit Testing) . . . . . . . . . . . . . . . . . . . . . . . . 11 3.6 Preparing the code for Function Verification Test (FVT) . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.6.1 Backing out a faulty FVT driver . . . . . . . . . 14 3.7 Dealing with Tracks/Features during FVT . . . . . . 14 3.8 Dealing with defects created during FVT . . . . . . 15 3.8.1 Severities for defects . . . . . . . . . . . . . 16 4.0 PREPARING THE BUILDS . . . . . . . . . . . . . . . . . 17 4.1 General assumptions . . . . . . . . . . . . . . . . 17 4.2 One-time only activities . . . . . . . . . . . . . . 17 4.2.1 Create CMVC family 'build' to be used with DB2 . 17 4.2.2 Create necessary links . . . . . . . . . . . . . 18 4.3 Creation of the Build/Ship/Package tree . . . . . . 20 4.4 Estimated time for build and packaging . . . . . . . 20 4.4.1 Estimated time for all combinations . . . . . . . 21 5.0 BUILDING THE CODE . . . . . . . . . . . . . . . . . . 23 5.1 Overview of the whole process . . . . . . . . . . . 23 5.2 Location of the source code . . . . . . . . . . . . 25 Contents vii 5.3 Build/Ship/Package directory structure . . . . . . . 25 5.3.1 Top directory structure - created via shell script 25 5.3.2 Source directory structure - created by extracting release 'cs230' . . . . . . . . . . . . . . . . . . . . 27 5.3.3 Install directory structure - created by extracting release 'inst230' . . . . . . . . . . . . . . . . . . . 29 5.3.4 Bottom directory structure - created by doing make with 'ship' . . . . . . . . . . . . . . . . . . . . . . 30 5.4 Activities to be done per each version, release or modification . . . . . . . . . . . . . . . . . . . . . . 31 5.4.1 Files that need to be modified due to changes in Copyright or VRM . . . . . . . . . . . . . . . . . . . . 31 5.4.2 Files that need to be modified when adding new files . . . . . . . . . . . . . . . . . . . . . . . . . 35 5.5 Preparation for the Build . . . . . . . . . . . . . 35 5.5.1 Process Tracks, Levels and Level Members . . . . 36 5.5.2 Extraction of the tools for the build and packaging process . . . . . . . . . . . . . . . . . . . . . . . . 36 6.0 BUILDING THE CMVC SERVER AND LINE COMMANDS . . . . . . 39 6.1 Complete cleanup of the Build tree . . . . . . . . . 39 6.1.1 Cleanup of the previous build . . . . . . . . . . 39 6.2 Extraction of the source files . . . . . . . . . . . 39 6.2.1 Extraction using Release or Level Extract . . . . 40 6.3 Building the code . . . . . . . . . . . . . . . . . 41 6.4 Miscellaneous notes . . . . . . . . . . . . . . . . 41 6.4.1 Notes on the MAKE.cmvc shell script . . . . . . . 41 6.5 Files affected by different MAKE.cmvc -c options . . 42 6.5.1 Making a DEBUG driver . . . . . . . . . . . . . . 44 6.5.2 Making an FVT driver . . . . . . . . . . . . . . 45 6.5.3 Making a BETA driver . . . . . . . . . . . . . . 45 6.5.4 Making a Gold driver . . . . . . . . . . . . . . 45 6.6 Gathering the shippable files (ship step) . . . . 46 6.7 Beta installation . . . . . . . . . . . . . . . . . 46 6.7.1 Known building problems . . . . . . . . . . . . . 46 6.7.2 Known Problems when Testing the code . . . . . . 48 7.0 BUILDING THE CMVC GUI . . . . . . . . . . . . . . . . 51 7.1 Build/Ship/Package directory structure for the GUI . 51 7.2 Preparation for the build . . . . . . . . . . . . . 52 7.3 Complete cleanup of the build tree . . . . . . . . . 52 7.4 Extraction of the source files . . . . . . . . . . . 52 7.4.1 Extraction using Release or Level Extract . . . . 52 7.5 Building the code . . . . . . . . . . . . . . . . . 53 7.5.1 Cleanup of object modules and message catalogs . 53 7.6 Considerations before building . . . . . . . . . . . 54 7.6.1 Making a DEBUG driver . . . . . . . . . . . . . . 54 7.6.2 Making an FVT driver . . . . . . . . . . . . . . 54 7.6.3 Making a BETA driver . . . . . . . . . . . . . . 54 7.6.4 Making a Gold driver . . . . . . . . . . . . . . 55 7.7 Building the GUI . . . . . . . . . . . . . . . . . . 55 7.8 Known build problems . . . . . . . . . . . . . . . . 56 7.9 Copying the output files into the ship directory . . 56 viii Building CMVC for UNIX 7.10 Performing a sanity test (based on a pseudo-installation) . . . . . . . . . . . . . . . . . . 56 7.10.1 Check the dates of the CMVC code recently built 57 7.10.2 Copy the CMVC code recently built into the install directories . . . . . . . . . . . . . . . . . . . . . . 57 7.10.3 Test the CMVC code recently built from the target host . . . . . . . . . . . . . . . . . . . . . . . . . . 58 7.10.4 Erase the CMVC code from the install directories (optional) . . . . . . . . . . . . . . . . . . . . . . . 58 8.0 PACKAGING THE CMVC SERVER, LINE COMMANDS AND GUI . . . 59 8.1 Overview of packaging for the Server . . . . . . . . 59 8.2 Overview of packaging for the Client (line commands and GUI) . . . . . . . . . . . . . . . . . . . . . . . . 60 8.2.1 Standalone files . . . . . . . . . . . . . . . . 60 8.2.2 Workbench Integrated files . . . . . . . . . . . 62 8.3 Preparing AIX smit installp images . . . . . . . . . 63 APPENDIX A. INTRODUCTION TO THE CHECKLISTS . . . . . . . . 65 A.1 Miscellaneous notes . . . . . . . . . . . . . . . . 65 APPENDIX B. CMVC FOR UNIX, BUILD AND PACKAGE STATUS CHECKLIST . . . . . . . . . . . . . . . . . . . . . . . 67 APPENDIX C. CMVC CLIENT/SERVER UNIX, BUILD AND PACKAGE CHECKLIST . . . . . . . . . . . . . . . . . . . . . . . 69 APPENDIX D. CMVC GUI FOR UNIX, BUILD AND PACKAGE CHECKLIST 75 APPENDIX E. HOW TO PUT THE CMVC CODE INTO TAPES . . . . . 77 E.1 How to get tapes via VM . . . . . . . . . . . . . . 77 E.2 Sequence to make a tape for CMVC . . . . . . . . . . 77 APPENDIX F. BIBLIOGRAPHY . . . . . . . . . . . . . . . . . 81 F.1 How to get electronic copies of manuals and TRs . . 81 F.1.1 IBM Intranet . . . . . . . . . . . . . . . . . . 81 F.1.2 Internet . . . . . . . . . . . . . . . . . . . . 82 APPENDIX G. COPYRIGHTS, TRADEMARKS AND SERVICE MARKS . . . 85 Contents ix FIGURES 1. get_opsys(): Shell script to find out name of operating system . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. motd: Shell script to edit and view the message-of-the-day . . . . . . . . . . . . . . . . . . . 8 3. Top directory structure - created manually via script 26 4. Source directory structure - created by release 'cs230' (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . 27 5. Source directory structure - created by release 'cs230' (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . 28 6. Bottom directory structure - created by release 'inst230' . . . . . . . . . . . . . . . . . . . . . . 29 7. Bottom directory structure - created by doing make with 'ship' . . . . . . . . . . . . . . . . . . . . . . . . 30 8. Header file with service keywords for the what command 32 9. Source file with service keywords for the what command 33 10. Files affected by different MAKE.cmvc -c options, part 1 43 11. Files affected by different MAKE.cmvc -c options, part 2 44 12. CMVC Client/Server UNIX, Build and Package Checklist, Level: ____ . . . . . . . . . . . . . . . . . . . . . 69 13. CMVC GUI for UNIX, Build and Package Checklist, Level: _____ . . . . . . . . . . . . . . . . . . . . . . . . 75 x Building CMVC for UNIX 1.0 BUILDING AND PACKAGING CMVC FOR UNIX The purpose of this technical report is to provide a real example of the use of CMVC for developing, maintaining, building and packaging a product in a heterogeneous client/server environment. CMVC itself is an excellent example, because we use CMVC itself to build the CMVC Server and Client using several operating systems and database management systems. We describe the challenges that we encounter when developing in heterogeneous environments and how we cope with them. Then we describe the development process that we used with CMVC for the development of the application. Then, in order to give you the extent of the complexity associ- ated with the development of an application in heterogeneous environments, we dedicate the rest of this document to the pre- requisites, configuration, building and packaging the CMVC Client and Server for UNIX. CMVC for UNIX is made available for the following operating systems: o AIX Version 3.2.5 o AIX Version 4 o HP-UX Version 9 o HP-UX Version 10 o Solaris 2.4 o SunOS 4.1.3 The CMVC Server for UNIX is built using the following relational databases (although we do not provide all possible combinations of operating system and database). o DB2 Version 1 o DB2 Version 2 o Oracle Version 7 Starting with Oracle 7.3, there were many APIs that were dropped from Oracle, and thus, CMVC is not compatible with Oracle 7.3. o Informix Version 5 o Informix Version 7 o Sybase 4.9 Although we do not do a native build on Sybase 10, the build on Sybase 4.9, works fine on Sybase 10. A set of quick status checklists with a summary of the build and package activities for the Client/Server code and the GUI code are provided in the appendices. Building and packaging CMVC for UNIX 1 1.1 DISCLAIMER The intention in writing this detailed process is certainly NOT to dictate to you the ONLY way to build the code; the intention is to document the process that we have used and that has proven to be successful. This process is NOT perfect and there is room for improvement, and you are welcome to improve it and to provide feedback to update this document to reflect that improvement. 2 Building CMVC for UNIX 2.0 CHALLENGES RELATED WITH HETEROGENEOUS ENVIRONMENTS There are several challenges that we faced during the development of CMVC for UNIX in a heterogeneous environment: o The main challenge is to maintain all needed combinations of hardware and software. o The next challenge was to seamlessly work across the dif- ferent platforms. To overcome this challenge we used the same shared userid in all systems called "build". o Then, we used the message-of-the-day (motd) to communicate between the developers and reserve working areas. 2.1 MAINTAINING ALL NEEDED COMBINATIONS OF HARDWARE AND SOFTWARE The main challenge is to maintain all needed combinations of hardware and software. The concurrent development of the CMVC Server for UNIX is done across multiple platforms/versions (6 variations), multiple hosts (9 machines), and multiple relational database management systems (6 variations). Furthermore, the development of the CMVC Client is done for standalone mode or integrated with SoftBench, plus in AIX and HP-UX we have to provide two versions, one for Motif 1.1/X11R4 and another for Motif 1.2/X11R5. Only in AIX 3.2.5, CMVC is provided in all combinations of data- bases and clients. In the other platforms, only certain combina- tions were needed. The tasks of obtaining the hardware and software, renewing the contracts, requesting and installing patches, providing mainte- nance (preventive and corrective) constitute a major portion of the development activities. 2.2 ROLE OF 'BUILD' USERID AND EXPORTED DIRECTORY All building activities in all operating systems is performed from the userid 'build' which has to have the same main charac- teristics in all the platforms: same user id number, same group id number and same home directory. Challenges related with heterogeneous environments 3 uid=210(build) gid=222(syscmvca) groups=0(system),1(staff),2(bin),3(sys),222(syscmvca) HOME=/home/build NOTES: * The groups should be appropriate to the platform * The group system is required because it builds a setuid-root application (cmvcd, the CMVC daemon). The actual home directory for this userid resides in an exported file system from a file server (in our case in host 'rtplib02') which must have enough capacity to hold the builds, install images and miscellaneous for all the needed combinations (in our case 2.5 GB). This exported file system is mounted in all other platforms, which have the same userid, groupid and home directory: mount rtplib02:/home/build /home/build The advantages of this scheme are: o This approach allows for maximum reuse and sharing of common files such as .profile and directories such as $HOME/bin. o It is possible to work simultaneously in the same 'build' account from different operating systems. For example, one developer could be doing a build for AIX 3 and DB2 V1 mean- while another developer could be using HP-UX 9 and Oracle 7. o It is possible to perform CMVC release and level extracts and use the same host and specify only the target directory. Furthermore, it is possible to specify the "nomount" option when extracting a release/level in order to not use NFS. This local extract is faster than an extract that involves NFS and avoids the risks mentioned in 2.2.1.1, "Risks of building code across NFS mounts" on page 5. o The number of host list entries in CMVC is reduced because the system login id is always "build". We need to create only those host list entries for our CMVC user ids and hostnames. One important consideration when using the CMVC GUI in such environment is that there is ONLY one "Cmvc" resource file and one CMVC tasks list. Furthermore, the developers need to be aware of the CMVC user id when using the GUI, because it will reflect the name of the previous developer. 4 Building CMVC for UNIX 2.2.1.1 Risks of building code across NFS mounts If your NFS setup is not too reliable, then you may have problems during the extraction of large releases or levels. One alterna- tive is to consider doing a local extract by using the "nomount" option; also, you can consider using AFS or DFS. New versions of NFS now support TCP instead of UDP to verify that each packet that is sent is actually received. When using NFS with UDP you should test the executables and search for compiled/linked objects of size 0 (zero): find . -size 0 -print 2.2.2 Standardize the location of ksh to /usr/bin/ksh ______________________________________________________ The latest generation of AIX and HP-UX have adopted the directory /usr/bin as the place to have the main user utilities, such as the "ksh" (Korn shell). This location affects the shell name used in the first line of our shell scripts, which we standardized as follows: #!/usr/bin/ksh In order to avoid a big pitfall with older versions of the oper- ating systems (the ksh cannot be found but the error message is extremely cryptic and confusing), it is necessary to do the fol- lowing symbolic link in those systems: ln -s /bin /usr/bin 2.2.3 Identifying the operating system _______________________________________ We used heavily in our tools the following routine (and shell script) to identify the version of the operating system: getopsys This was specially important to identify the Solaris system because even though Solaris and the old SunOS are NOT binary com- patible, the data given by the UNIX "uname" utility is mis- leading, because for Solaris systems, the name "SunOS 5.x" is used to identify the "Solaris 2.x" systems. Challenges related with heterogeneous environments 5 #!/usr/bin/ksh #----------------------------------------------------------------------+ # NAME: get_opsys # # Return a string identifying the operating system. # Output: OPSYS = (AIX, HP-UX, SunOS, Solaris) # # Notes about uname: # * The command "uname -a" returns the following information: # # operating_system_name node_name release_name version_name # # * Examples of uname: # # AIX 3: AIX carcps06 2 3 000011985C00 # AIX 4: AIX oem-ppc3 1 4 000022559000 # HP-UX 9: HP-UX oem-hp02 A.09.03 E 9000/735 2000248696 8-user license # HP-UX 10: HP-UX oem-hp01 B.10.01 A 9000/735 2010377972 two-user license # Solaris 2.4: SunOS oem-sn01 5.4 generic sun4m sparc # SunOS 4.1.3: SunOS oem-sn03 4.1.3_U1 1 sun4m # #----------------------------------------------------------------------+ get_opsys() { raw=`uname -a` OPSYS=`echo $raw | cut -f1 -d' '` # Test for Solaris (5... or higher) or SunOS (4...) # The problem is that the Solaris op-sys is identified as SunOS, and # there is no string that indicates that is "Solaris". The distinction # is done only by the version number. if [ "$OPSYS" = "SunOS" ] then var=`echo $raw | cut -f3 -d' ' | cut -c1-1` if [ $var -ne 4 ] then OPSYS="Solaris" fi fi export OPSYS echo "get_opsys: " $OPSYS } get_opsys # end of file Figure 1. get_opsys(): Shell script to find out name of operating system 6 Building CMVC for UNIX 2.2.4 Shared .profile ______________________ The shared .profile has to be comprehensive enough to accommodate for the differences between platforms and databases. For example, the location of one utility may be /bin in one system or /usr/bin in another. We use the name of the host inside a case statement in order to provide environment variables that deal with these differences. 2.3 USING A BULLETIN TO COMMUNICATE NEWS (MESSAGE-OF-THE-DAY) Because the same build directory is used across the systems, it is important to have a "bulletin" for messages to avoid colli- sions with the usage of subdirectories. It is recommended to use the file $HOME/motd (for "Message Of The Day") to place a note that would be of importance to the other users of the build directory. This file is displayed immediately after the logon and before the first prompt. An example is shown below: System/DB: Orac7.0 Orac7.1 Orac7.2 Inf5 Inf7 DB2v1 DB2v2 Syb4.9 Syb10 oem-ibm AIX3 X X X X carcps08 AIX3 X X-1 oem-ppc1 AIX4 X X oem-ppc3 AIX4 X X oem-sn01 solaris X X X oem-sn03 sunOS X X X oem-hp02 V9 X X oem-hp04 V9 X-2 X oem-hp03 V10 X X Notes 1: Database is available, but not currently running 2: Database is installed, but not configured. Release: cs230 cmvc230/aix3/cs/informix5 - L 022, Mig DB2 & docs - Angel cmvc230/aix3/cs/oracle7 - L 024, Austin stuff - Lee cmvc230/sunos/cs/sybase49 - L 024+, bug X - JRY (oem-sn01) cmvc230/sunos/cs/oracle7 - L 024+, bug X - JRY (oem-sn01) cmvc230/hp10/cs/informix7 - L 024+, bug X - JRY (oem-hp03) Release: gui230 cmvc230/solaris/gui/x11r5/stal - PMRs - Angel The shell script used for displaying the message of the day is shown below: Challenges related with heterogeneous environments 7 #!/usr/bin/ksh # # Edit and update the message-of-the-day (motd) # Take last line of file and save in temporary file outfile="/tmp/motd.build" let x=`cat $HOME/motd | wc -l | tr -d ' '` let y=$x-1 head -$y $HOME/motd > $outfile echo Entering vi to edit current motd echo Note: do not enter date, it will be appended automatically sleep 2 # Edit file and append time/date stamp chmod u+w $outfile vi $outfile echo Exiting motd, date is being appended echo "***End $HOME/motd as of `date`. 'motd' to update***" >> $outfile mv $HOME/motd $HOME/motd.old # Save old file and install new one cp $outfile $HOME/motd if [ -f $outfile ] then rm $outfile else echo "Error, new motd not copied. Saving $outfile" fi # Show results clear echo "Displaying new motd:" sleep 2 cat $HOME/motd exit 0 # end of file Figure 2. motd: Shell script to edit and view the message-of-the-day 8 Building CMVC for UNIX 3.0 OVERALL PROCESS WITH CMVC CMVC is used to manage the software configuration and the file changes for the CMVC Server and Client for UNIX. This section describes the overall process for handling the files and the dif- ferent CMVC objects associated with the CMVC Server and Client for UNIX. 3.1 FAMILIES, COMPONENTS AND RELEASES The CMVC 2.3.0 product is developed and maintained in the "toro" family. The components and releases are: o The main component for the server and the line commands in the toro family is cmvc and the release is cs230. o The component for the tools to install the code in the toro family is called cmvcInstallp and the release is inst230. o The component for the GUI in the toro family is called cmvcgui and the release is gui230. o The parent component for the obsolete components and releases is called "OBSOLETE". In this way, these obsolete objects do not clutter the tree view of the active components. The components have the default process which include the Verify subprocess for Defects and Features and the Design, Size and Review subprocess for Features (and not for Defects). The releases have the Fix, Track and Level subprocesses during all the development phases. The Approval subprocess is activated during the times when the code is about to be prepared for ver- ification and for packaging; in that way, the changes to the release are carefully monitored and controlled. Instead of three separate releases, it might be possible to use only one release for all the code (line commands, GUI, installa- tion tools), which could minimize the overhead associated with tracks and levels. However, we found that having three releases gives us also much needed flexibility for handling situations where the development activities concentrated on the server code and there were frequent code changes, and thus, we could continue at slower pace of change with the GUI. For business reasons, the CMVC version/release 2.3.0 was the only one that we did, and we just provide full refreshes of the release; that is, the latest refresh supersedes the previous one, and there are no deltas to be delivered and applied. We identify Overall process with CMVC 9 these refreshes by using the CMVC Level as the 4th identifier from left to right; for example, our latest refresh for the code was Level 18 or refresh 2.3.0.18. Thus, we did not encounter the situation where we had to create a new release (such as one for version 2.4 or 3.1) and we did not have to maintain the links of files between multiple releases. 3.2 PROCESS MODEL This section describes the development process followed by the CMVC development team to handle defects and features. There are three important characteristics in this process: o There is only one active level at a time. This avoids the problem of having prerequisite tracks that are in another active level (spaghetti tracks). o The criteria to commit a level is that the code can be built successfully, regardless if the function is working as desired. This guarantees that any level can be extracted and built correctly. If the level builds fine, but if there are functional prob- lems, then new defects are created and handled in the next level. We try to avoid a large number of file changes and tracks in a level. We would rather have many small levels than a single extremely large level. There are a couple of reason for this decision: - The Level -check and Level -commit are by far the most expensive operations in CMVC, in terms of CPU usage and in exploitation of the database. - If you wait a long time before committing a level, then the users who created defects or features will not see any verification records and the testers of your software may not see a driver built in a long time. While reading this document, it might be helpful to have a copy of the Appendix A "CMVC State Diagram", page 72 from the CMVC Concepts manual. In this way you will be able to follow the state transitions and the relationships between the elements. 10 Building CMVC for UNIX 3.3 PROJECT LEAD CREATES COMPONENTS AND RELEASES 1. The project lead creates the necessary components under the family. 2. These components use the Design-Size-Review (DSR) subprocess for features, but the DSR subprocess will not be used for defects. The verify subprocess will be used for both fea- tures and defects. 3. The project lead creates under the appropriate component the relevant releases. Each release should use the subprocesses fix, track, test and level. Depending on the stage of the release, it might be necessary to add the approval subprocess. Originally we used the test subprocess when the team was larger and we had one tester fully dedicated to CMVC, but now that the team is smaller, we found that the verification records provide us with the opportunity to ensure that the fix indeed addressed the problem. Thus, we do not use the test subprocess anymore. 3.4 HANDLING DEFECTS AND FEATURES 1. The project lead or a team lead will assign to the developers the appropriate defects and features to be implemented. 2. The developers accept the defects and the defects move to the 'working' state. 3. The features are designed, sized, reviewed, and accepted, until eventually they will be in the 'working' state. 4. A track is created to associate each defect or feature with the appropriate release or releases. 3.5 DEVELOPERS WORK WITH FILES USING TRACKS (CODE AND UNIT TESTING) This is the phase for Coding and Unit Testing. 1. The developers will create/check-out, compile, test, debug and check-in the files affected by the release. Because the release uses the track subprocess, during check-in, the developers need to specify the appropriate track. Overall process with CMVC 11 The existing files that are not changed as a result of the feature (but need to be included during the compilation), are extracted. We recommend that the user performs a release/level extract of the committed version. 2. All the components that have file changes will have a a fix record for a track. You can see the fix record by selecting the "Fix Records..." option from the "Windows" pulldown in the "CMVC - Tracks" window. 3. You can see the file changes in a track by selecting the "Change History" option from the "Show" pulldown in the "CMVC - Tracks" window. 3.6 PREPARING THE CODE FOR FUNCTION VERIFICATION TEST (FVT) Once the developers decide that it is time to integrate the code and go to the Function Verification Test (FVT) phase, then the following actions will take place: The project leader will confer with the developers to make sure that all the files that will be in FVT must have completed the unit testing. 1. The project leader will create a level for the release. The initial state of the level is 'working'. 2. The fix records for each relevant track need to be completed. Ideally, the component owner for the fix record should review the code that was changed, and then mark the fix record as completed. This action will certify that the code compiles at the individual level and that unit testing has been per- formed. However, in practice, this step is done only on difficult file changes where a second opinion is advisable. 3. When all the fix records are marked as completed, then the track is moved from the 'fix' state to the 'integrate' state. 4. For each track, a level member has to be created for the level. The level member window can be shown by selecting the "Level Members" option from the "Windows" pulldown in the "CMVC - Levels" window. This action will move the level to the 'integrate' state. 12 Building CMVC for UNIX This action is done by the builder, who is the person in charge of adding the tracks to the level and then extracting the level in order to compile the code. 5. Then a build is done of the level in order to produce the testing driver for the release. For more information, see the process document for the build activity. 6. If a problem is found during the compilation/linking of the code from the level and if a change has to be done in a file, then it is necessary to move the track to the "fix" state; in order to do that it is necessary to do the steps described in 3.6.1, "Backing out a faulty FVT driver" on page 14. 7. Before extracting the level, it is necessary to check it in order to ensure that all file changes are present, and that there are no missing prerequisites. If there are missing prerequisites, then the missing tracks should be added or the appropriate tracks present in the level should be removed (in case the prerequisite track is not ready to be integrated). 8. If starting a build from scratch, then the builder will perform a full extract of the latest committed level. Then, the builder will extract the Delta of the current integrated Level. If not starting from scratch, then a Delta of the current Level might be sufficient. In case of doubt, delete the current build tree and do a full level extract plus a delta extract. 9. If no problems were found during the build activity, then the level is committed and completed. 10. We may change the value for the level field "type" to indi- cate how the code will be distributed: o Gold, if the code is going to be part of a standalone CD-ROM or participate in the IBM Software Solutions for AIX Showcase CD-ROM. o Refresh, if the code is just going to be placed in the internal and external FTP sites for users to download. o Beta, if the code is going to be delivered to few cus- tomers as beta code. Overall process with CMVC 13 3.6.1 Backing out a faulty FVT driver ______________________________________ If during the preparation of an FVT driver, a problem is found, then it could be necessary to back-out the offending track, fix the files, and repeat the process. This 'backing out' action can be accomplished by following the steps below: 1. Remove the level member associated with the track that con- tains the file or files to be modified. This can be done by selecting the "Remove" option from the "Actions" pulldown in the "CMVC - Level Members" window. 2. Move the track from the "integrate" state to the "fix" state, so that the files in question can be modified. This can be done by selecting the "Fix" option from the "Actions" pulldown in the "CMVC - Tracks" window. 3. Activate the fix records for the track. This can be done by selecting the "Activate" option from the "Actions" pulldown in the "CMVC - Fix Records" window. 4. Check-out, modify the contents of the files, compile, test, and check-in the files again. 5. Complete the fix records; this action will move the track to the integrate state. 6. Go back to step 5 on page 13. 3.7 DEALING WITH TRACKS/FEATURES DURING FVT 1. Once the level moves to the "complete" state, the tracks move to the "test" state. In case the release does not have an environment list, then the track moves to the "complete" state. 2. Once the track is in the "test" state, then the FVT tester will test the code and will have the opportunity to accept, abstain, or reject the track. Originally we had a full-time tester and thus we needed the test subprocess, but now our team is smaller and we do not use the test subprocess, instead we use the verification records. 3. If no problems are encountered that are related to the track/feature at hand, then the tester will "accept" the test record for the track. 14 Building CMVC for UNIX To access the test record, select the "Test Records..." option from the "Windows" pulldown in the "CMVC - Tracks" window. 4. If the tester finds a problem, then the tester will "reject" the test record. Then the tester should open a defect reporting the problem. See 3.8, "Dealing with defects created during FVT." 5. Once the test records for a track have been accepted/rejected/abstained, the track moves to the "com- plete" state. This in turn moves the defect or feature to the "verify" state. 6. The originator of the defect or feature is notified that the defect or feature is now in the verify state, and then the verification record for the defect or feature needs to be accepted, rejected, or abstained. When the verification records are modified, the defect or feature moves into the "complete" state. 7. If the verification record is rejected, the originator MUST create a new defect or feature in order to correct the prob- lems. NOTE: After a verification record is rejected or abstained, CMVC will NOT automatically create a new defect or feature. 3.8 DEALING WITH DEFECTS CREATED DURING FVT 1. The testers will create defects for those problems encount- ered during FVT. The component owners will be notified by CMVC of the new defects and they will handle the defects, such as accept, reject, assign. 2. For each accepted defect, the owner of the defect needs to create a track. 3. Repeat the process of adding the track to a level. Overall process with CMVC 15 3.8.1 Severities for defects _____________________________ The definition of the severities that are used for the defects is shown below: 1. Function can not be used. Immediate fix is necessary. 2. Function can be used but with serve restrictions. 3. Function can be used with minor restrictions, not critical. 4. Function can be bypassed, but should be corrected. 16 Building CMVC for UNIX 4.0 PREPARING THE BUILDS 4.1 GENERAL ASSUMPTIONS o For each operating system it is necessary to have a build host with the appropriate hardware and software. o The build for each platform/database combination has to be done in each platform (no cross-compiler available). o A single userid, build, will be used for all building activities. o The relational database has to already be installed and a database (for example, in DB2 this is called a database instance) with the name of "build" has to be created. o The task of building and packaging the complete product for all the environments is complex and prone to error due to the magnitude of the combinations. It is suggested to use the checklist described in Appendix C, "CMVC Client/Server UNIX, Build and Package Checklist" on page 69 to keep track of the progress for each build. 4.2 ONE-TIME ONLY ACTIVITIES 4.2.1 Create CMVC family 'build' to be used with DB2 _____________________________________________________ It is necessary to create a CMVC family named 'build' on each platform in order to perform the pre-compilation steps to resolve the SQL queries with the actual database. This CMVC family must have the following characteristics: login: build gid: The database name 'build' is used in the Make.. make scripts. After the database has been created: 1. Execute "db2 connect to build" Preparing the builds 17 2. The results should be: Database Connection Information Database product = DB2/6000 1.1.0 SQL authorization ID = BUILD Local database alias = BUILD 3. Execute "db2 connect reset" 4.2.2 Create necessary links _____________________________ In order to have a common interface for the build process, in some cases it is necessary to provide symbolic soft links between the actual path for the databases/tools and the paths used inside the MAKE.cmvc and related files. To do these links, it is necessary to execute the following command as root: ln -s 4.2.2.1 AIX o Host oem-ibm and database sybase49: ln -s /home/sybase/sybase49 /usr/db/sybase49 o Host carcps08 and database oracle7.0: ln -s /db/oracle/product/7.0.13 /usr/oracle7 o Host oem-ppc1 and database oracle7.1: ln -s /home/oracle71 /usr/oracle71 o Host carcps08 and database informix: ln -s /db/informix /usr/informix 4.2.2.2 HP-UX o Host oem-hp03 and database oracle7: ln -s /cmvc_db/u2/oracle/product/7.0.12 /usr/oracle7 o Host oem-hp03 and database informix: 18 Building CMVC for UNIX ln -s /users/informix /usr/informix o Host oem-hp02 and database informix: ln -s /users/informix /usr/informix ln -s /users/informix /usr/db/informix 4.2.2.3 SunOS o Host oem-sn03 and database sybase49: not needed o Host oem-sn03 and database oracle7: ln -s /home/oracle/product/7.0.12 /usr/oracle7 o Host oem-sn03 and database informix: ln -s /home/informix /usr/informix 4.2.2.4 Solaris o Host oem-sn01 and Softbench: ln -s /opt/softbench /usr/softbench o Host oem-sn01 and database sybase49: ln -s /export/home2/sybase/sybase49 /usr/db/sybase49 The Oracle 7.1.6 code for Solaris is installed in a system that is a local drive in oem-ibm, thus, it is necessary to mount it: mount oem-ibm:/home/lv03 /export/home3 o Host oem-sn01 and database oracle7: ln -s /export/home3/ora716 /usr/oracle7 Preparing the builds 19 4.3 CREATION OF THE BUILD/SHIP/PACKAGE TREE To create the top portion of the Build/Ship/Package tree (to be called just "Build tree") as shown in 5.3.1, "Top directory structure - created via shell script" on page 25, do the fol- lowing: 1. Login in as 'build'. 2. Create the directory that will complete the specification of TOP, such as 'cmvc230'. In this way the $TOP will be $HOME/cmvc230. 3. Change to the directory 'bin'. 4. Use CMVC to extract the file "mkbldtree" from release "tools230". 5. Create the directory for the Version-Release of CMVC, such as 'cmvc230'. 6. Change to the directory 'cmvc230'. The shell script will create the build tree from the current directory. 7. Execute the shell script as follows: mkbldtree 4.4 ESTIMATED TIME FOR BUILD AND PACKAGING The average approximate time involved in a single complete build is shown below. However, the compilation times may range from 2 hours in fast machines such as oem-hp04 to 5 hours in slow machines such as oem-ibm. Furthermore, this average time should be multiplied for each com- bination of platform and database to be built. This time assumes that this is not the first build, and assumes that all the hardware and software is operational, and that the one-time activities have been performed already. The breakdown is shown below (in hours) Extract the installation/source files: 0.5 Perform the build: 4.0 Package the files: 1.0 Perform the installation test: 1.0 20 Building CMVC for UNIX 4.4.1 Estimated time for all combinations __________________________________________ The approximate time involved in a complete build for all the combinations of platform/database is: 1 full-time week (40 hours) Preparing the builds 21 22 Building CMVC for UNIX 5.0 BUILDING THE CODE 5.1 OVERVIEW OF THE WHOLE PROCESS It takes approximately one full working week to do a complete build from scratch for a single CMVC level, such as 2.3.0.21. As we add more platforms (such as AIX 4 and HP-UX 10) and more databases (Oracle 7.1 and Informix 7 and DB2 V2), the whole process will keep getting larger and larger, and taking more disk space everywhere. This time frame gives the luxury to do barely any testing at all: no installation test, no regression tests, no sanity tests. The status checklist for the builds, Appendix B, "CMVC for UNIX, build and package status checklist" on page 67 is the "score card" or "cheat sheet" that was used in level 2.3.0.21 and you can appreciate the enormous amount of work that is involved here, and why it is so time consuming to prepare "special beta" ver- sions for demanding customers, because these versions take a long time to prepare and usually is a throw away effort that cannot be reused, and many times we do not have file space to keep around the old version (non-beta) of an install file and the beta version of the install file demanded by the customer. Furthermore, it is difficult to fully automate the process because of many limitations: network problems, disk space, manual specification of the options to build, etc. The CMVC Level is NOT committed until all the builds are done. Once all the compilations in all the platforms are clean, then the level can be committed. This means that if a bug is encount- ered after the level is committed, a defect will be opened for the next level. The reason for this is to guarantee that a full extract of a level is buildable in all platforms, even though the function itself may not be correct. The whole sequence for the complete preparation for a single level is summarized below and is further explained in detail in other sections in this document: 1. Tell other CMVC developers to stop using the affected direc- tories and to do a checkin or a copy to another directory of any files that are important to them. 2. Delete "rm -fr" the appropriate top directory, such as cmvc230/aix4/cs/db2 Building the code 23 3. Do a full extract of the latest committed level, such as 020. 4. Do a delta extract of the current non-committed level, such as 021. 5. Login as build into the specific system to use, such as "oem-ppc1" for AIX 4 for DB2 V2. 6. Modify manually "qmake" to use the appropriate options, such as normal, db2v2, aix4, and all (both server and client). 7. Start "qmake" and monitor its progress. There are some compilations that usually fail and require manual intervention, such as Solaris and SunOS. The workarounds are known and easy to apply manually, but there is no way to automate them. 8. After the compilation is done, then do "qmake ship" to copy the shippable code into the "ship" directory. 9. Repeat the extract and build process for the GUI, for both the standalone and the integrated version of the client. 10. Also in AIX 3 it is necessary to build the GUI for X11R4 and X11R5, and in HP-UX 9 it is necessary to build the GUI for X11R4 and X11R5. 11. As root, change directory to /home/build/cmvc230/installp and kickoff the "make -f Makefile..