diff --git a/src/makeBaseApp/iocAppBuildSRcontrol.html b/src/makeBaseApp/iocAppBuildSRcontrol.html index 66d4fcb5b..4af7b215d 100644 --- a/src/makeBaseApp/iocAppBuildSRcontrol.html +++ b/src/makeBaseApp/iocAppBuildSRcontrol.html @@ -1,7 +1,7 @@ - + EPICS: IOC Applications: Building and Source Release Control @@ -15,20 +15,21 @@ Source Release Control

-Marty Kraimer and Janet Anderson 
-Argonne National Laboratory, Advanced Photon Source 
-June 12, 1998 
+Marty Kraimer, Janet Anderson , and Ralph Lange
+June 15, 1998 
EPICS Release 3.13.0.beta12

-Acknowledgements

+Changes since beta11 Between release 3.13.0.beta11 and 3.13.0.beta12 makeBaseApp was changed from one very long perl script to a four page perl script plus template files. It supports templates in addition to those supplied with EPICS base. -Other improvements were made including support for capfast. The following -people contributed to this effort: Ralph Lange (BESSY),  Rozelle Wright -(LANL) and Thomas Birke (BESSY). +Other improvements were made including support for capfast. The primary +developer of the new version of makeBaseApp was Ralph Lange (BESSY). Rozelle +Wright (LANL) and Thomas Birke (BESSY) contributed to this development. +In addition no soft links are required so that makeBaseApp works on winXX +hosts.

Quick Start

@@ -384,8 +385,7 @@ to meet these needs.

Overview of Application Source Release Control

The application directory structure appears as follows: -
    iocsys/
-        <top>/
+
        <top>/
             config/
             xxxApp/
                 src/
@@ -414,10 +414,12 @@ developers as needed. The iocBoot directory contains a subdirectory for
 each IOC that belongs to that <top> area. No IOC belongs to
 more than one <top> area. All software components needed by
 IOCs are built in the xxxApp directories. Each IOC is booted from bin/<target_arch>
-and uses a startup file from it's subdirectory under iocBoot. The
-only important source file in a boot directory is the st.cmd file
-which is executed after vxWorks is started on an IOC. The st.cmd file
-loads various files built in the xxxApp directories.
+(actually from any directory containing a vxWorks and vxWorks.sym
+compatible with the version of vxWorks against which the target was built)
+and uses a startup file from a subdirectory under iocBoot. The only important
+source file in a boot directory is the st.cmd file which is executed
+after vxWorks is started on an IOC. The st.cmd file loads various
+files built in the xxxApp directories.
 
 
Application developers decide what constitutes a <top>.
 For example, at APS, the Linac is completely contained in a single <top>
@@ -467,11 +469,17 @@ If it is necessary to obtain a bug fix or enhancement to a single module
 from EPICS base or a share release, the application developer
 has at least two choices. The first is to build a new release of base or
 share. A second choice is to copy the source module to an appropriate
-src directory and build it there. In this case you should do something
-so that you remember to use the version from share after share
-is rebuilt.
+src directory and build it there. In this case the developer must
+remember to use the version from share after share is
+rebuilt.
 
 
Note: Other software packages can be handled like share.
+

+templates

+The makeBaseApp.pl utility creates new application areas. It does this
+by copying and transforming directory trees from a template area. EPICS
+base provides templates for a simple application and for an example application.
+Each site can, however, create their own set of templates.
 

 Tools

 The following tools are used:
@@ -532,8 +540,10 @@ Structure
             RULES_ARCHS
             RULES_DIRS
             RULES_TOP
+            makeDbDepends.pl
             makeIocCdCommands.pl
-        xxxApp/
+            replaceVAR.pl
+        xxxApp/ or xxxapp
             src/ or xxxSrc or xxxsrc
                 Makefile
 *               Makefile.Host
@@ -541,16 +551,17 @@ Structure
 *               base.dbd
 *               baseLIBOBJS
 *               <app>Include.dbd
-*               <example and/or user supplied code>
-*               <example and/or user supplied state programs>
-*               <user menu, recordtype, device, driver database defs>
-            Db/ or xxxDb or xxxdb
+*               <source code>
+*               <state programs>
+*               < menu, recordtype, device, driver database defs>
+            Db/ or db or xxxDb or xxxdb
                 Makefile
 *               <record instance files>
 *               <record template and substitution files>
             privately managed directories
-        iocBoot/
+        iocBoot/ or iocboot
             Makefile
+            Makefile.Host
             nfsCommands
             iocxxx/
 *               Makefile
@@ -558,6 +569,8 @@ Structure
 **              cdCommands
 **      dbd/
             <installed database description files>
+**      db/
+            <installed record instance files>
 **      include/
             <installed include files>
 **      bin/
@@ -566,9 +579,7 @@ Structure
             <ioc_arch>
                 <installed IOC products>
             ...
-**      lib/
-**      man/
-**      db/

+**      lib/
Files marked with an "*" are user created and/or edited. Each such file is discussed in this section. @@ -586,12 +597,12 @@ The directories are: Directory containing configuration files for gnumake.
-xxxApp
+xxxApp or xxxapp
Directory containing source files and database files. An arbitrary number of xxxApp directories are allowed. Each must have App -appended to the name because Makefile looks for it.
+or app appended to the name because Makefile looks for it.
@@ -614,7 +625,7 @@ substitution files or the equivalent CapFast schematics.
-iocBoot
+iocBoot or iocboot
Directory containing a subdirectory for each IOC.
@@ -657,13 +668,6 @@ Library Directory. This directory contains a subdirectory for the host architecture and for each target architectiure. These are the directories in which libraries are installed. -
-man
- -
-Man pages Directory. This directory contains a subdirectory for each section -of the Unix style man pages. This is where man pages are installed.
-
db
@@ -688,9 +692,19 @@ This is the file in which you add to or modify make variables in EPICS base. A useful definition to override is: 
    CROSS_COMPILER_TARGET_ARCHS =
+ +
This specifies the vxWorks architecture to build. If your site builds base for multiple target architectures but your IOCs only use a single architecture, -overriding this variables saves build time. +overriding this variables saves build time.
+ +
+If you are using capfast you may want to add the definition:
+ +
+
DB_OPT = YES
+
+
CONFIG_APP
@@ -962,7 +976,6 @@ EPICS_MBA_TEMPLATE_TOP  Template top directory 
    mkdir <top>    # If <top> does not exist
     cd <top>
     <base>/bin/<arch>/makeBaseApp -t <apptype> <app> ...
-    or
     <base>/bin/<arch>/makeBaseApp -i -t <apptype> <ioc> ...
makeBaseApp does the following:
  • @@ -1125,7 +1143,6 @@ For each <app> specified on the command line a directory <app is created and populated with the directory tree from the template (with ReplaceLine() tag replacement).
    • - - EPICS base supplies the following sets of template files xxxApp
    -The most useful command at this level is
    +Two useful commands at this level are -
        gnumake rebuild
    -which is the same as issuing "gnumake rebuild" in each subdirectory of -xxxApp. +
    +
    + +
    +
    +
    gnumake
    + +
    or
    + +
    gnumake rebuild
    +
    +
    + +
    +which is the same as issuing the command in each subdirectory of xxxApp.
    + +
     
    xxxApp/src or xxxApp/xxxSrc
    @@ -1423,20 +1455,56 @@ Running the command: 
        gnumake
    -in a src directory builds and installs all out of date Host and -IOC components described by the files Makefile.Host and Makefile.Vx. -The builds are performed in subdirectories O.<arch>.
    +which is the same as executing "gnumake install"  builds +and installs all out of date Host and IOC components described by the files +Makefile.Host and Makefile.Vx. The builds are performed +in subdirectories O.<arch>. +
      +
    +It is possible to build for a single architecture via the command:
    -

    It is possible to build for a single architecture via the command: +

        gnumake <arch>
    +
    + +
    For example, if your IOC is an MV167 system, then the directory is O.mv167, -and the make command is: +and the make command is:
    + +
        gnumake mv167
    -Another useful command is: +
    + +
    +Another useful command is:
    + +
        gnumake clean
    +
    + +
    This removes the host and target architecture directories created by make. -".<arch>" can be appended to invoke clean for a particular architecture. +".<arch>" can be appended to invoke clean for a particular architecture.
    + +
    +
    + +
    +The command:
    + +
    +
    +
    gnumake rebuild
    +
    +
    + +
    +is the same as "gnumake clean install".
    + +
    +
    +
    xxxApp/xxxDb
    @@ -1444,19 +1512,28 @@ This removes the host and target architecture directories created by make. Executing gnumake in this directory generates and installs database instance files, template and substitution files plain sources or CapFast schematics. +
    +
    +
    iocBoot
    -The most useful command at this level is
    +Executing 
        gnumake
    -which is the same as issuing "gnumake" in each subdirectory of iocBoot. + +
    +is the same as issuing "gnumake" in each subdirectory of iocBoot.
    + +
    +
    +
    iocBoot/iocxxx
    -Running gnumake in this directory creates the cdCommands +Executing gnumake in this directory creates the cdCommands file.
    @@ -1935,7 +2012,7 @@ specified in DB), must be specified:         USES_TEMPLATE += $(SHARE)/installDb/zzz.template If specified with a path (full or relative), the templates will be soft -linked (UNIX) resp. copied (WIN) into the O.<arch> directory. +linked (UNIX) or copied (WIN) into the O.<arch> directory. After the first make run, template dependencies will be generated automatically.

    If there is no *.substitutions source for a needed substitutions file, @@ -1943,6 +2020,10 @@ but a variable defining a script name (like CREATESUBSTITUTIONS=CreateSubst. this script will be called with the prefix of the substitution file name to be generated. +

    NOTE: If (and only if) there are script generated substitutions files, +the prefix of any inflated database's name may not equal the prefix of +the name of any template used within the directory. +

    Other definitions: 

    E2DB_FLAGS      e2db options
 SCH2EDIF_FLAGS  sch2edif options
    @@ -2025,9 +2106,10 @@ CVSROOT Your environment variable CVSROOT should point to the CVS repository for IOC Applications. The following command displays the location of CVSROOT: 
        echo $CVSROOT
    -At APS/ASD the command should show: +For example, at APS/ASD the command should show: 
        /usr/local/iocapps/cvsroot
    - +At APS all <top> applications are stored under $CVSROOT/iocsys. +Other sites may use a different convention.

    Commands

    This section gives a brief description of the CVS commands. Wherever <filename> @@ -2046,53 +2128,21 @@ Typing 
        cvs help
    gives overall cvs help. -
    -Initial Checkout
    - -
    -Each user performs application development in his/her private area. The -developer must checkout iocsys/ascf. Then entire <top> -areas can be checked out or else just a subset of a <top> area.
    - - -

    The first step is to checkout ascf. The easiest way is to create the -application area with a high level directory called iocsys. The -following commands are issued: -

        cd <anywhere>
-    cvs checkout iocsys/ascf
    -iocsys will appear as a subdirectory of <anywhere>. -If <anywhere> is null then iocsys appears in the user's -home directory. +
     
    Checkout Entire <top> Area
    To check out an entire <top> area issue the commands:
    -
        cd <anywhere>
-    cvs checkout iocsys/<top>
    +
    cd <anywhere>
+cvs checkout iocsys/<top>
    iocsys/<top> appears under <anywhere>
    -
    -Checkout Subset of <top> Area
    -
    -It is possible to checkout a subset of the the xxxApps and a subset -of the iocBoot directories. The commands to accomplish this are:
    - -
        cd <anywhere>
-    cvs checkout iocsys/<top>/Makefile
-    cvs checkout iocsys/<top>/config
-    cvs checkout iocsys/<top>/xxxApp
-    ...
    -The entire iocBoot directory can be checked out via the command: -
        cvs checkout iocsys/<top>/iocBoot
    -A subset of the iocBoot directory can be checked out via the commands: -
        cvs checkout iocsys/<top>/iocBoot/Makefile
-    cvs checkout iocsys/<top>/iocBoot/iocxxx
-    ...
    +
    watch