diff --git a/READMEbuildingR3.13AppsWithR3.14.html b/READMEbuildingR3.13AppsWithR3.14.html new file mode 100644 index 000000000..e0b167d7e --- /dev/null +++ b/READMEbuildingR3.13AppsWithR3.14.html @@ -0,0 +1,252 @@ + + + + + + + + + Instruction on building existing R3 + + + + + + + +

+Building EPICS R3.13 applications with R3.14.0alpha2 base

+This document describes how to convert a R3.13 vxWorks application so that +it builds with release R3.14.0alpha2.  It describes an easy way to +convert applications subject to the following restrictions: + +Ultimately applications should be converted to use the new configure rules +so that the OSI features are available. +

+Gnumake clean uninstall

+At the top of the application execute: +
"gnumake clean uninstall"
+to remove all files and directories created by earlier builds. +

+Update RELEASE

+Change  the EPICS_BASE definition to point to the R3.14 base release. +In addition all hardware support and some soft support is now unbundled. +For example the sequencer is unbundled. You must obtain and build all required +unbundled products before you can build the application. The location of +each unbundled product must be described in <top>/config/RELEASE. +

+Update target arch definitions

+Change any target arch specification in config/CONFIG to new base R3.14 +target arch specification. Look in the R3.14 base/bin to see the target +arch names. +

For example, in config/CONFIG change +

CROSS_COMPILER_TARGET_ARCHS = mv167
+to +
CROSS_COMPILER_TARGET_ARCHS = vxWorks-68040
+In the iocBoot/*/Makefile files, change +
ARCH=<old arch name>
+to +
ARCH=<new arch name>
+and do a "gnumake" in the iocBoot directory to update the cdCommands +files. +

+SNC changes

+snc is no longer in base. If snc is used in your application, you must +download and build the seq module with baseR3.14.0alpha2 or later. See +the Application Developer's Guide to see how to build sequence programs. +

+iocCore changes

+iocCore has been renamed to iocCoreLibrary.o. +
Change +
INSTALLS=iocCore
+to +
LIBOBJS = $(EPICS_BASE_BIN)/iocCoreLibrary.o
+in your application src/Makefile.Vx files to link iocCore into your application +library. +
Also remove +
ld < iocCore
+from the st.cmd files in the iocBoot subdirectories. +

+Library db changes

+The Db library name was changed to dbStaticHost for host builds and dbStaticIoc +for ioc builds. +
Change +
PROD_LIBS+=Db
+to +
PROD_LIBS+=dbStaticHost
+and +
Db_DIR=$(EPICS_BASE_LIB)
+to +
dbStaticHost_DIR=$(EPICS_BASE_LIB)
+in your application src/Makefile.Host files. +

+VxWorks C++ munched libraries and object files

+Since R3.14 contains C++ code, the build rules were changed to create a +corresponding munched file for every vx object file built. The objects +files can be combined to form libraries but the munched files must be loaded +into vxWorks. In all st.cmd files add the suffix ".munch" to the ld lines +where object files were previously loaded. For example change +
ld < exampleLib
+to +
ld < exampleLibrary.munch
+ +

+recGbl calls

+You may need to add the line  "#include "recGbl.h" to any +source files that have recGbl* calls so that the file will compile without +errors. +

+Record support changes

+The steppermotor, scan, and pid records are no longer in base. If your +application does not use these record types, comment out or remove references +to them in base.dbd and baseLIBOBJS. If these record types are used by +your application you must download and build the modules with R3.14 base, +add appropriate module definitions to your application's config/RELEASE +fileand change the LIBOBJS definitions. For example +
add +
PID=<full path to modules directory>/pid
+to config/RELEASE. +
Remove +
LIBOBJS += $(EPICS_BASE_BIN)/pidRecord.o
+from baseLIBOBJS, +
and add +
LIBOBJS += $(PID_BIN)/pidRecord.o
+to your application src/Makefile. +

You should consider changing any existing old steppermotor records to +the new EPICS  motor +record  module supported by Beamline Controls and Data Acquisition +at APS. +

+RecDynLink.o and devPtSoft changes

+recDynLink.o and devPtSoft.o are no longer in base. Remove references to +them in base.dbd and baseLIBOBJS if they are not used in application. +

+Hardware support changes

+All hardware support (dev, drv and dbd files) has been unbundled from base +R3.14. This support includes the files symb.dbd, drvHp1404a.o, drvEpvxiMsg.o, +and drvEpvxi.o.  If they are not used in your application, comment +out references to these files in base.dbd and baseLIBOBJS. +

Hardware support files now exist as separate modules available for download +from the EPICS www home page at +ANL. You must now download all the hardware support modules needed +for your application, build the modules with R3.14 base,  add the +appropriate module full path definitions to your application config/RELEASE +file, and change LIBOBJS location definition $(EPICS_BASE_BIN) +to the module definition bin directory in your application src directory +files. +

For example, remove +

LIBOBJS+=$(EPICS_BASE_BIN)/symb
+from baseLIBOBJS and add +
LIBOBJS+=$(SYMB_BIN)/symb
+to your application src/Makefile, +
and add the line +
SYMB=<full path definition for the built module SYMB>
+ into your application config/RELEASE file . +

After a gnumake in the symb module followed by a gnumake in the application +config directory, the definitions SYMB_BIN and SYMB_LIB +will be created,  the directory $(SYMB)/include will be added to the +include directories on the compiler command lines  (in the INSTALL_INCLUDES +definition)  and the directory $(SYMB)/dbd will be added to the dbd +search directories on the dbExpand command lines (in the INSTALL_DBDFLAGS +definition). +

+dbLoadtemplate tool changes

+The host tool dbLoadTemplate has been replace by a new extension, msi. +dbLoadTemplate is still supported on iocs. Build the msi extension with +base R3.14 and change definitions the following definitions in your application +files. +

In config/RULES.Db replace the line +

DBLOADTEMPLATE=$(EPICS_BASE_HOST_BIN)/dbLoadTemplate$(EXE)
+with +
MSI = $(firstword $(wildcard $(EPICS_EXTENSIONS_HOST_BIN)/msi$(HOSTEXE) \
+   (EPICS_EXTENSIONS)/bin/$(HOST_OS_CLASS)/msi$(HOSTEXE)) msi$(HOSTEXE))
+and change line: +
@$(DBLOADTEMPLATE) $< > $@
+to +
@$(MSI) $< > $@
+Also add the definition +
EPICS_EXTENSIONS=<full path name to epics extensions directory>
+to your application config/RELEASE file. + + diff --git a/READMEbuildingR3.13ExtensionsWithR3.14.html b/READMEbuildingR3.13ExtensionsWithR3.14.html new file mode 100644 index 000000000..e1d07ce60 --- /dev/null +++ b/READMEbuildingR3.13ExtensionsWithR3.14.html @@ -0,0 +1,132 @@ + + + + + + + + + +

+Building EPICS R3.13 extensions with R3.14.0alpha2 base

+ +
EPICS R3.13 extensions have both a Makefile and a Makefile.Host +in the build directories and the EPICS R3.13 extension tree has an extensions/config +directory.
+ +

+Preliminary steps for all extensions

+ +
+
  • +Download the latest version (10/25/00) of the extensions/config files, +extensionsConfig.tar.gz,  from the APS EPICS www page.
    • + +
  • +Make certain that you have set the HOST_ARCH environment variable.
    • + +
  • +Set EPICS_BASE in extensions/config/RELEASE to the full path location of +a built R3.14.0alpha2 base.
    • + +
  • +BASE_3_14 is now defined in the alpha2 file, base/config/CONFIG_BASE_VERSION.  +The commented BASE_3_14 definition can be removed from extensions/config/RELEASE.
    • +
    + +

    +Building downloaded APS distribution extensions with base R3.14.0alpha2

    + +
    +
  • +Download the latest version (10/25/00) of extensions distributed from the +APS EPICS www page. The latest versions of the extensions should build +with both R3.13 and R3.14. Note that the order of building extensions is +important, i.e. some extensions depend on other extensions being built +first. The extensions/config/CONFIG_EXTENSIONS file contains notes on extension +dependancies and contains a definition of DIRS (used by extensions/src/Makefile) +with the proper order for building the APS distributed extensions.
    • + +
  • +Executing gnumake at the root level of the extensions tree or in the src +directory should build the APS extensions in the proper order.
    • +
    + +

    +Building your extensions with base R3.14.0alpha2

    + +
    +
  • +Library Db renamed
    • + +
    Library Db has been renamed to dbStaticHost in EPICS base R3.14. In +some extensions lib Db is not used and Db can be removed from the USR_LIBS +(or PROD_LIBS) line. If the library is needed ( you get unresolved items +after removing Db), the following lines should be added to Makefile.Host. +
    ifdef BASE_3_14 +
    USR_LIBS += dbStaticHost +
    dbStaticHost_DIR = $(EPICS_BASE_LIB) +
    else +
    USR_LIBS += Db +
    Db_DIR = $(EPICS_BASE_LIB) +
    endif
    + +
  • +Target architecture specifications changed
    • + +
    Since target architecture specifications have been changed (solaris +to solaris-sparc, win32 to win32-x86, ...) Makefile.Host references to +and tests on T_A have to be changed.  In most cases T_A can be replaced +by OS_CLASS.  Since HOST_ARCH will eventually be phased out, it would +be a good idea to change any Makefile.Host references to HOST_ARCH to OS_CLASS +if possible. +
    For example change +
    ifeq ($(T_A),solaris) +
    RPCFLAGS = -K -1 +
    endif
    +to +
    ifeq ($(OS_CLASS),solaris) +
    RPCFLAGS = -K -1 +
    endif
    + +
  • +New ca_set_puser
    • + +
    Statements of the form: ca_puser(chid) = xyz; should to be +changed to:  ca_set_puser(chid,xyz); +
      +
  • +Extern C around includes
    • + +
    Remove any extern "C" braces around #includes of EPICS base header +files. +
    For example change +
    extern "C" { +
    #include "cadefs.h" +
    } /* end extern C */
    +to +
    #include "cadefs.h"
    + +
  • +Infrequently used R3.13 timestamp functions unbundled from base
    • + +
    Some infrequently used R3.13 timestamp functions and macro definitions +have been removed from EPICS base and now exist in a library, ts, created +and installed in the ar extension.  The only ANL distributed extension +that uses these unbundled functions and macros  is cau. The two R3.13 +functions tsStampToText and tsLocalTime along with the definitions TS_TEXT_MONDDYYYY +and TS_TEXT_MMDDYY have been retained in R3.14 for extension compatibility +purposes. +
    If your extension gets undefines for TS_* usage and ts* function calls +when built with R3.14, you must obtain and build the ar extension. Add +an #include for tsSubr.h to your extension source code and add library +ts to PROD_LIBS or USR_LIBS in your Makefile.Host as follows: +
    #include "tsSubr.h" +

    ifdef BASE_3_14 +
    PROD_LIBS += ts +
    ts_DIR = $(EPICS_EXTENSIONS_LIB) +
    endif

    +
    + + + diff --git a/READMEconvertingR3.13AppsToR3.14.0alpha2.html b/READMEconvertingR3.13AppsToR3.14.0alpha2.html new file mode 100644 index 000000000..5b832b593 --- /dev/null +++ b/READMEconvertingR3.13AppsToR3.14.0alpha2.html @@ -0,0 +1,263 @@ + + + + + + + + + +

    +Converting an EPICS R3.13 application to R3.14.0alpha2

    +This document describes how to convert a R3.13 vxWorks application so that +it builds with release R3.14.0alpha2.  It describes procedures such +that: + + + + +

    +Gnumake clean uninstall

    +First do a gnumake clean uninstall in the application's root directory +to remove all files created by earlier builds. +

    +Create a new R3.14 application

    + +
    mkdir <top> +
    cd <top> +
    /home/phoebus/JBA/epics/base/bin/solaris-sparc/makeBaseApp.pl -t example +example
    + +

    +Copy all *App and iocBoot directories and files to the new <top> directory

    + +
    cd <oldtop> +
    find *App iocBoot -print | cpio -pvmd <fullpath name to new top>
    + +

    +Modify <top>/configure/RELEASE

    + +
    Copy definitions of external modules excluding EPICS_BASE and +TEMPLATES_TOP from old application release file. +
    If sequence programs (*.st or *.stt files) exist in your application, +add the SNCSEQ location definition for the R3.14 seq external module +
    SNCSEQ =<full path to seq top>
    +The R3.14 seq module must exist and be built with EPICS base R3.14.0alpha2.
    + +

    +Modify the Makefiles in <top>/*App directories.

    + +
    Change     include $(TOP)/config/CONFIG_APP +
    to     include $(TOP)/configure/CONFIG +

    Change     include $(TOP)/config/RULES_DIRS +
    to     include $(TOP)/configure/RULES_DIRS

    + +

    +Modify the Makefiles in <top>/*App/*Db directories.

    + +
    Remove existing Makefile +
    Rename Makefile.Host to Makefile +
    Modify Makefile as follows: +

    Change     TOP=../../.. +
    to     TOP=../.. +

    Change    include $(TOP)/config/CONFIG_APP +
    to     include $(TOP)/configure/CONFIG +

    Change     include $(TOP)/config/RULES.Db +
    to     include $(TOP)/configure/RULES +

    Place all definitions between the include lines. +

    Place any rules after the last include line.

    + +

    +Modify the Makefiles in <top>/*App/src directories.

    + +
    Remove existing Makefile +
    Rename Makefile.Host to Makefile +
    Modify Makefile as follows: +

    Change TOP=../../.. +
    to     TOP=../.. +

    Change     include $(TOP)/config/CONFIG_APP +
    to     include $(TOP)/configure/CONFIG +

    Change     include $(TOP)/config/RULES.Host +
    to     include $(TOP)/configure/RULES +

    Change     PROD_LIBS = Db +
    to     PROD_LIBS = dbStaticHost +

    Change     Db_DIR = $(EPICS_BASE_LIB) +
    to     dbStaticHost_DIR = $(EPICS_BASE_LIB) +

    Change     USER_DBDFLAGS +
    to     USR_DBDFLAGS +

    Change     RECTYPES +=  xxxRecord.h +
    to     DBDINC += xxxRecord +

    Change     DBDNAME = <name>.dbd +
    to     DBD += <name>.dbd +

    Remove all DBDEXPAND  lines. +

    Add the contents of Makefile.Vx to Makefile removing the include lines +and the TOP definition.

    + +
    Change     LIBNAME = <libname> +
    to     LIBRARY_vxWorks = <libname> +

    Add the line   <libname>_OBJS = $(LIBOBJS) +

    Change     INSTALLS = iocCore seq +
    to +

    <libname>_OBJS_vxWorks += $(EPICS_BASE_BIN)/iocCoreLibrary +
    <libname>_OBJS_vxWorks += $(SNCSEQ_BIN)/seqLibrary +
    <libname>_OBJS_vxWorks += $(SNCSEQ_BIN)/pvLibrary +
    <libname>_OBJS_vxWorks += $(SNCSEQ_BIN)/pvCaLibrary
    +Change     include ../baseLIBOBJS +
    to     -include ../baseLIBOBJS +

    Change    SRCS +=  <srcname>.c +
    to     <libname>_SRCS += <srcname>.c +

    Rename your sequence programs from <name>.st to <name>.stt  +if they do not need  c preprocessing before conversion. +

    Change    LIBOBJS += <seq_program_name>.o      +lines +
    to   <libname>_SRCS += <seq_program_name>.stt +
    or  <libname>_SRCS += <seq_program_name>.st +

    Place all macro definitions between the include lines. +

    Place any rules after the last include line.

    + +

    +Modify the Makefiles in <top>/iocBoot directory.

    + +
    Change include $(TOP)/config/CONFIG_APP +
    to     include $(TOP)/configure/CONFIG +

    Remove the line DIRS += $(wildcard *ioc*) +

    Change include $(TOP)/config/RULES.iocBoot +
    to     include $(TOP)/configure/RULES.iocBoot

    + +

    +Modify the Makefiles in <top>/iocBoot/ioc* directories.

    + +
    Change include $(TOP)/config/CONFIG_APP +
    to     include $(TOP)/configure/CONFIG +

    Change include ARCH = <old arch specification e.g. mv167> +
    to     include ARCH = <new arch specificatio +e.g. vxWorks-68040> +

    Change include $(TOP)/config/RULES.ioc +
    to     include $(TOP)/configure/RULES.ioc

    + +

    +Modify st.cmd in <top>/iocBoot/ioc* directories.

    + +
    Remove the lines
    + +
    +
    +
    ld < seq
    + +
    ld < iocCore
    +
    +Change       ld < <libname> +
    to      ld < <libname>Library.munch +

    Change  load statements  for db and dbd files from +

    cd startup +
    dbLoadDatabase("../../dbd/exampleApp.dbd") +
    dbLoadRecords("../../db/dbExample1.db","user=jba") +
    dbLoadRecords("../../db/dbExample2.db")
    +to +
    cd top +
    dbLoadDatabase("dbd/example.dbd") +
    registerRecordDeviceDriver(pdbbase) +
    dbLoadRecords("db/dbExample1.db","user=jba") +
    dbLoadRecords("db/dbExample2.db")
    +
    + +

    +Record support changes

    + +
    The steppermotor, scan, and pid records are no longer in base. +If these record types are used at your site, they  should be downloaded +and built with base R3.14 by your EPICS administrator. To update the R3.14 +location of these record types in your application you must  add appropriate +module definitions to your application's config/RELEASE file and change +the LIBOBJS definitions. +

    For example add

    + +
             PID=<full +path to modules directory>/pid +

    to config/RELEASE. +
    Remove

    + +
             LIBOBJS += +$(EPICS_BASE_BIN)/pidRecord.o +
    from baseLIBOBJS, +
    and add
    + +
             LIBOBJS += +$(PID_BIN)/pidRecord.o +
    to your application src/Makefile.
    + +
    You should consider changing any existing old steppermotor +records to the new EPICS  motor record  module supported by Beamline +Controls and Data Acquisition at APS.
    + +

    +RecDynLink.o and devPtSoft changes

    + +
    recDynLink.o and devPtSoft.o are no longer in EPICS base and +now exist as separate EPICS modules.You must now add the appropriate module +full path definitions to your application config/RELEASE file, and change +LIBOBJS location definition $(EPICS_BASE_BIN) to the module definition +bin directory in your application src directory files.  See "Hardware +support changes" below for instructions.
    + +

    +Hardware support changes

    + +
    All hardware support (dev, drv and dbd files) except soft support +has been unbundled from base R3.14. This support includes the files symb.dbd, +drvHp1404a.o, drvEpvxiMsg.o, and drvEpvxi.o.
    + +
    Hardware support now exists as separate EPICS modules. The +hardware support for your site should be downloaded and built with base +R3.14 by your EPICS administrator. You must now add the appropriate module +full path definitions to your application config/RELEASE file, and change +LIBOBJS location from $(EPICS_BASE_BIN) to the module  bin directory +in your application src directory files. +

    For example, remove

    + +
             LIBOBJS+=$(EPICS_BASE_BIN)/symb
    + +
    from baseLIBOBJS and add
    + +
             LIBOBJS+=$(SYMB_BIN)/symb
    + +
    to your application src/Makefile, +
    and add the line
    + +
    +
    SYMB=<full path definition for the built module SYMB>
    +
    + +
    into your application config/RELEASE file .
    + +

    +dbLoadtemplate tool changes

    + +
    The host tool dbLoadTemplate has been replace by a new EPICS +extension, msi, which should be downloaded and built with base R3.14 by +your EPICS administrator. dbLoadTemplate is still supported on iocs.  +If, in your application, db files are created from template and substitution +files you should  add the definition +

             EPICS_EXTENSIONS=<full +path name to epics extensions directory> +

    to your application config/RELEASE file.

    + +
    +
     
    + +
    +
    
+
    
+
    
+
+
     
+
+