packages/vms/curl_gnv_build_steps.txt

   1 From File: curl_gnv_build_steps.txt
   2
   3  Copyright 2009, John Malmberg
   4
   5  Permission to use, copy, modify, and/or distribute this software for any
   6  purpose with or without fee is hereby granted, provided that the above
   7  copyright notice and this permission notice appear in all copies.
   8
   9  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  15  OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16
  17 Currently building Curl using GNV takes longer than building Curl via DCL.
  18 The GNV procedure actually uses the same configure and makefiles that
  19 Unix builds use.
  20
  21 Building CURL on OpenVMS using GNV requires GNV V2.1-2 or the updated
  22 images that are available via anonymous FTP at encompasserve.org in the gnv
  23 directory.  It also requires the GNV Bash 4.2.45 kit as an update from the
  24 same location or from the sourceforge.net GNV project.
  25
  26 The HP C 7.x compiler was used for building the GNV version.
  27
  28 The source kits are provided in backup savesets inside of the PCSI install kit.
  29
  30 Backup save sets are currently the only distribution medium that I can be
  31 sure is installed on a target VMS system that will correctly unpack files
  32 with extended character sets in them.  You may need to adjust the ownership
  33 of the restored files, since /Interchange/noconvert was not available at the
  34 time that this document was written.
  35
  36 [gnv.common_src]curl_*_original_src.bck is the original source of the curl kit
  37 as provided by the curl project.  [gnv.vms_src]curl-*_vms_src.bck, if present,
  38 has the OpenVMS specific files that are used for building that are not yet in
  39 the curl source kits for that release distributed http://curl.haxx.se
  40
  41 These backup savesets should be restored to different directory trees on
  42 an ODS-5 volume(s) which are referenced by concealed rooted logical names.
  43
  44 SRC_ROOT: is for the source files common to all platforms.
  45 VMS_ROOT: is for the source files that are specific to OpenVMS.
  46           Note, you should create the VMS_ROOT: directory tree even if it is
  47           initially empty.  This is where you should put edits if you are
  48           making changes.
  49 LCL_ROOT: is manually created to have the same base and sub-directories as
  50           SRC_ROOT: and VMS_ROOT:
  51
  52 The logical name REF_ROOT: may be defined to be a search list for
  53 VMS_ROOT:,SRC_ROOT:
  54
  55 The logical name PRJ_ROOT: is defined to be a search list for
  56 LCL_ROOT:,VMS_ROOT:,SRC_ROOT:
  57
  58 For the make install process to work, it must have write access to the
  59 directories referenced by the GNU: logical name.
  60
  61 In future releases of GNV, and with GNV Bash 4.2.45 installed, this name
  62 should be GNV$GNU:
  63
  64 As directly updating those directories would probably be disruptive to other
  65 users of the system and require elevated privilege, this can be handled by
  66 creating a separate directory tree to install into which can be referenced
  67 by the concealed rooted logical name new_gnu:.  A concealed logical name of
  68 OLD_GNU: can be set up to reference the real GNV directory tree.
  69
  70 Then a local copy of the GNU/GNV$GNU logical names can be set up as a search
  71 list such as NEW_GNU:,OLD_GNU:
  72
  73 The directory NEW_GNU:[usr] should be created.  The make install phase should
  74 create all the other directories.
  75
  76 The make install process may abort if curl is already because it can not
  77 uninstall the older version of curl because it does not have permission.
  78
  79 The file stage_curl_install.com is used set up a new_gnu: directory tree
  80 for testing.  The PCSI kitting procedure uses these files as input.
  81
  82 These files do not create the directories in the VMS_ROOT and LCL_ROOT
  83 directory trees.  You can create them with commands similar to:
  84
  85   $ create/dir lcl_root:[curl]/prot=w:re
  86   $ copy src_root:[curl...]*.dir -
  87     lcl_root:[curl...]/prot=(o:rwed,w:re)
  88   $ create/dir vms_root:[curl]/prot=w:re
  89   $ copy src_root:[curl...]*.dir -
  90     vms_root:[curl...]/prot=(o:rwed,w:re)
  91
  92 One of the ways with to protect the source from being modified is to have
  93 the directories under src_root: owned by a user or resource where the build
  94 username only has read access to it.
  95
  96
  97 Note to builders:
  98
  99 GNV currently has a bug where configure scripts take a long time to run.
 100 Some of the configure steps take a while to complete, and on a 600 Mhz
 101 DS10 with IDE disks, taking an hour to run the CURL configure is normal.
 102 The bug appears to be in the SED for GNV 2.1.3 and GNV 3.0.1 where it
 103 is taking far longer than it should to do I/O.  In addition, there are
 104 reports that the SED in GNV 3.0.1 is broken so the SED from GNV 2.1.3
 105 should be used instead.
 106
 107 The following messages can be ignored and may get fixed in a future version
 108 of GNV.  The GNV$*.OPT files are used to find the libraries as many have
 109 different names on VMS than on Unix.  The Bash environment variable
 110 GNV_CC_QUALIFIERS can override all other settings for the C Compiler.
 111
 112 ? cc: No support for switch -warnprotos
 113 ? cc: Unrecognized file toomanyargs
 114 ? cc: Warning: library "ssl" not found
 115 ? cc: Warning: library "crypto" not found
 116 ? cc: Warning: library "gssapi" not found
 117 ? cc: Warning: library "z" not found
 118 u unimplemented switch - ignored
 119
 120
 121 With these search lists set up and the properly, curl can be built by
 122 setting your default to PRJ_ROOT:[curl.packages.vms] where the * is
 123 replaced by the actual version of curl, and then issuing the command:
 124
 125   $ @build_gnv_curl.com.
 126
 127 This command procedure does the following:
 128
 129   $ @setup_gnv_curl_build.com
 130
 131   $ bash gnv_curl_configure.sh
 132
 133   $ @clean_gnv_curl.com
 134
 135   $ bash make_gnv_curl_install.sh
 136
 137   $ @gnv_link_curl.com
 138
 139   $ @stage_curl_install.com
 140
 141   $ purge new_gnu:[*...]/log
 142
 143 To clean up after a build to start over, the following commands are used:
 144
 145    $ bash
 146    bash$ cd ../..
 147    bash$ make clean
 148    bash$ exit
 149
 150 Then run the @clean_gnv_curl.com.  Use the parameter "realclean" if you are
 151 going to run the setup_gnv_curl_build.com and configure script again.
 152
 153    $ @clean_gnv_curl.com realclean
 154
 155 If new public symbols have been added, adjust the file gnv_libcurl_symbols.opt
 156 to have the new symbols.  If the symbols are longer than 32 characters,
 157 then they will need to have the original be exact case CRC shortened and
 158 an alias in upper case with CRC shortened, in addition to having an exact
 159 case truncated alias and an uppercase truncated alias.
 160
 161 The *.EXE files are not moved to the new_gnu: directory.
 162
 163 After you are satisfied with the results of your build, you can move the
 164 files from new_gnu: to old_gnu: at your convenience.
 165
 166 Building a PCSI kit for an archictecture takes the following steps after
 167 making sure that you have a working build environment.
 168
 169 Note that it requires manually creating two logical names as described
 170 below.  It is intentional that they be manually set.  This is for
 171 branding the PCSI kit based on who is making the kit.
 172
 173    1. Make sure that you have a staging directory that can be referenced
 174       by the path STAGE_ROOT:[KIT]
 175
 176    2. Edit the file curl_release_note_start.txt or other text files to
 177       reflect any changes.
 178
 179    3. Define the logical name GNV_PCSI_PRODUCER to indicate who is making
 180       the distribution.  For making updates to an existing open source
 181       kit you may need to keep the producer the same.
 182
 183    4. Define the logical name GNV_PCSI_PRODUCER_FULL_NAME to be your full
 184       name or full name of your company.
 185
 186    5. If you are producing an update kit, then update the file
 187       vms_eco_level.h by changing the value for the VMS_ECO_LEVEL macro.
 188       This file is currently only used in building the PCSI kit.
 189
 190    6. Edit the file PCSI_GNV_CURL_FILE_LIST.TXT if there are new files added
 191       to the kit.  These files should all be ODS-2 legal filenames and
 192       directories.
 193
 194       A limitation of the PCSI kitting procedure is that when selecting files,
 195       it tends to ignore the directory structure and assumes that all files
 196       with the same name are the same file, so every file placed in the kit
 197       must have a unique name.  Then a procedure needs to be added to the kit
 198       to create an alias link on install and remove the link on remove.
 199
 200       Since at this time curl does not need this alias procedure, the steps
 201       to automatically build it are not included here.
 202
 203       While newer versions of PCSI can support ODS-5 filenames, not all verions
 204       of PCSI on systems that have ODS-5 filenames do.  So as a post install
 205       step, the PCSI kit built by these steps does a rename to the correct
 206       case as a post install step.
 207
 208    7. Edit the build_curl_pcsi_desc.com and build_curl_pcsi_text.com if you
 209       have changed the version of ZLIB that curl is built against.
 210
 211    8. Prepare to backup the files for building the kit.
 212
 213       Note that if src_root: or vms_root: are NFS mounted disks, the
 214       step of backing up the source files will probably hang or fail.
 215
 216       You need to copy the source files to VMS mounted disks and create
 217       logical names SRC_ROOT1 and VMS_ROOT1 to work around this to to
 218       reference local disks.  Make sure src_root1:[000000] and
 219       vms_root1:[000000] exist and can be written to.
 220
 221       The command procedure compare_curl_source can be used to check
 222       those directories and keep them up to date.
 223
 224          @compare_curl_source.com SRCBCK UPDATE
 225
 226          This compares the reference project source with the backup
 227          staging directory for it and updates with any changes.
 228
 229          @compare_curl_source.com VMSBCK UPDATE
 230
 231          This compares the VMS specific source with the backup
 232          staging directory for it and updates with any changes.
 233
 234          Leave off "UPDATE" to just check without doing any changes.
 235
 236       If you are not using NFS mounted disks and do not want to have a
 237       separate directory for staging the sources for backup make sure
 238       that src_root1: and vms_root1: do not exist.
 239
 240    9. Build the PCSI kit with @pcsi_product_gnv_curl.com
 241
 242        The following message is normal:
 243           %PCSI-I-CANNOTVAL, cannot validate
 244             EAGLE$DQA0:[stage_root.][kit]VMSPORTS-AXPVMS-CURL-V0731-0-1.PCSI;1
 245           -PCSI-I-NOTSIGNED, product kit is not signed and therefore has
 246           no manifest file
 247
 248        This will result in an uncompressed kit for the target platform.
 249        On Alpha and Integrity, the pcsi_product_gnv_curl.com can be used with
 250        the "COMPRESSED" parameter to build both a compressed and uncompressed
 251        kits.
 252
 253 Good Luck.