vms/readme.vms - third_party/libssh2 - Git at Google

 *These are the porting notes to OpenVMS, as of 7 April 2010
 by Jose Baars. This file will be installed as
 libssh2*.release_notes by the product install kit.


 LIBSSH2
 -------

 LIBSSH2 is a client-side library written in C that aims to
 implement the SSH2 protocol. It is an open source project,
 to be found at http://libssh2.org.

 GNV
 ---

 The library uses the GNV prefix, on advise of the kind supporter
 of the GNV project, John Malmberg.

 Installing the PCSI kit
 =======================

 Prerequisites
 -------------
 - VMS version 8.3 minimal.
   See the remarks at prerequisites for building the kit
 - TCP/IP stack, both TCP/IP services and Multinet should work.
   See the remarks at prerequisites for building the kit
 - HP OPENSSL V1.3 minimal.
   See the remarks at prerequisites for building the kit
 - JEM  ZLIB V1.2-3E1 minimal.
   See the remarks at prerequisites for building the kit

 The first three dependencies are tested at installation time, and
 installation will fail if any these products are not installed.
 The ZLIB dependency is not tested by the product installation
 procedure, as libssh2 will probably be installed as part of
 multiple libraries including zlib.

 Install
 -------


 The kit will install gnv$libssh2.exe in a directory tree that might
 already be available on your system if you have installed other gnv*
 libraries or utilities.

 The directory tree for gnv$libssh2.exe will be like this:

 [gnv] -- [usr] -- [include] -- [libssh2] include files for libssh2
                   [lib] gnv$libssh2_x_y_z.exe
                   [share]   -- [doc] -- [libssh2] libssh2.hlb,
                                         release notes (this file),
                                         libssh2 release notes

 optional:
                                         [example] libssh2_examples-x_y_z.bck
                   [common_src] libssh2-x_y_z_src.bck

 By default, it will install the shared image and include files to
 SYS$COMMON:[GNV...].

 You can override this destination by specifying the destination
 directory after /DESTINATION= on the product install command line.
 This is particularly of use when installing the library on a cluster
 without a common system disk.

 Please ignore the following warnings, as the kit is not signed :

 %PCSI-I-CANNOTVAL, cannot validate dev:[dir]JCB-AXPVMS-LIBSSH2-V0102-05D20100402-1.PCSI
 -PCSI-I-NOTSIGNED, product kit is not signed and therefore has no manifest file

 Optionally, you can install a backup saveset with some programming examples,
 or a backupo saveset with the complete libssh2 source tree.

 you will need to answer 'NO' to the question
 'Do you want the default for all options'.

 and 'YES' to either or both the following questions:

     Do you want the libssh2 C programming examples ?  [NO]

     Do you want the complete libssh2 source tree ?  [NO]


 Post installation tasks
 -----------------------

 Although we will try to maintain upward compatibility of libssh2,
 this can not be guaranteed by the libssh2 project itself for OpenVMS,
 nor eternally by us.

 To use libssh2 effectively, you will have to define a system logical
 to point to the shared image. If you are willing to take the gamble,
 define this logical in your systartup like so:

 $ define/system/executive gnv$libssh2 dev:[dir..]gnv$libssh2_x_y_z.exe

 Optionally, you can install the executbale like so:

 $ mc sysgen install dev:[dir..]gnv$libssh2_x_y_z.exe/open/share/header

 Link your programs against gnv$libssh2, and when upgrading libssh2
 test thoroughly.

 If you want to be extra cautious define a system logical like this:

 $ define/system/executive gnv$libssh2_x_y_z dev:[dir..]gnv$libssh2_x_y_z.exe

 Link  programs against gnv$libssh2_x_y_z, and when upgrading libssh2
 link against new versions.

 It is probably more convenient in the last case to link against the object
 library provided in the source backup saveset. Both an uppercase and a
 mixed case object library, called libssh2.olb and libssh2_asis.olb
 are provided.


 Compiling and linking against libssh2
 -------------------------------------

 The  shared image library has a vector table with both uppercase and
 mixed case entry points, allowing to link directly against the shared
 image wether you need the /NAMES=AS_IS or not.

 To link successfully, you MUST use /NAMES=shortened, as some function
 names in libssh2 are longer than the VMS maximum of 32 characters.

 If you chose to install the examples, you can unpack the backup
 saveset by

 backup/sel=*.c device:[gnv.usr.share.doc.libssh2.examples]libssh2_examples-x_y_z.bck -
  []

 They can by compiled and linked by these commands ( provided you have defined
 the gnv$libssh2 logical) :

 $ cc/include=dev:[gnv.usr.include.libssh2] xxx.c/names=shortened
 $ link/opt=sys$input: xxx.obj
 gnv$libssh2/share


 Building gnv$libssh2
 ====================

 You can build gnv$libssh2 yourself, which may have advantages, as the library is
 in full development, very regularly new features are added.

 For production use, it is probably advisable to use a stable version, and
 link against that. To check out new features, statically linking against
 the object library is probably more practical, to avoid compatibility
 issues.


 Prerequisites
 -------------

 You will need to have the following available:

 - An Alpha or Itanium VMS system. Due to dependencies on zlib, ssl and ODS-5,
   support on VAXen would be cumbersome at least.

 - VMS version 8.3 minimal. This is a requirement of gnv$zlibshr.exe against
   which shared image library libssh2 is linked. If you use another zlib
   to link against, you can make it work under lower versions of VMS.
   I have made it work on VMS 7.3-2 with not a lot of difficulty.
   Also, if you are not interested in compression, you can choose not
   to link against zlib at all; in that case comment out the
   #define  LIBSSH2_HAVE_ZLIB in libssh2_config.h.

 - TCP/IP services or Multinet for OpenVMS.
   TCPWare has not been tested.

 - The HP OpenSSL product. Of course, with tweaking, you can probably link
   it against the OpenSSL library, but that is not what I have used.

 - A C compiler. I don't know any other working C compilers than
   the DEC/Compac/HP-C compiler on VMS.

 - An ODS-5 disk. With tweaking you'll get it to work on an ODS-2
   disk, but it is unpractical to do so.

 - A version of VMSTAR that understands ODS-5 disks and extended
   filenames. Look here:
   http://ftp.process.com/ftp/vms-freeware/fileserv/vmstar.zip

 - gunzip, available for instance at Steven M Schweda's website:
   http://antinode.info/ftp/gzip/gzip-1_3_12b_vms/gzip-1_3_12b_vms.zip

 Optional:

 - curl, to be found at  http://curl.haxx.se
   You might want to use curl to download the libssh2 kit directly
   to you VMS machine. Interestingly, sftp in curl is implemented using
   libssh2, soon to be expected on VMS as well, hopefully.

 Downloading libssh2
 -------------------

 At the website of libssh2, you can find stable and daily gzipped
 tarballs. if you have a computer connected to internet you can
 download a daily build yourself by a procedure that looks a lot like
 this ( fill out your own proxy user/password, set up right symbols to
 gunzip, vmstar and curl and set up the libssh2 build version):

 $ libssh2_version = "1.2.6"
 $!
 $ proxy_line = " ""-U"" ""''proxy_userpass'""  ""-x"" ""''proxy_hostport'"" "
 $!
 $ currentday = f$cvtime(,,"date") - "-" - "-"
 $!
 $ set def mydev:[mydir.libssh2]
 $!
 $ if f$search("libssh2-''libssh2_version'-''currentday'.tar.gz") .nes. ""
 $ then
 $   delete libssh2-'libssh2_version'-'currentday'.tar.gz;*
 $ endif
 $!
 $ curl 'proxy_line' "http://libssh2.org/snapshots/libssh2-''libssh2_version'-''currentday'.tar.gz" -
                     -o libssh2-'libssh2_version'-'currentday'.tar.gz
 $!
 $!
 $ if f$search("libssh2-''libssh2_version'-''currentday'.tar.;") .nes. ""
 $ then
 $   delete libssh2-'libssh2_version'-'currentday'.tar.;*
 $ endif
 $!
 $ gunzip libssh2-'libssh2_version'-'currentday'.tar.gz
 $!
 $ tarfile = f$search("libssh2-''libssh2_version'-''currentday'.tar.;")
 $ vmstar xf 'tarfile'

 Downloading a stable build will need you to get rid of the currentday.

 After the download, you should have a directory tree with a toplevel
 directory called [libssh2-x.y.z-yyyymmdd].
 One of the subdirectories is called vms.

 Getting the libssh2 sources from the source backup in the binary kit
 --------------------------------------------------------------------

 During installation of the binary kit, you are given the option
 of installing the sources. If chosen, a backup saveset with
 the complete libssh2 directory is made available in
 [gnv.common_src].

 By restoring this backup saveset, you end up with the same
 set of files as by the direct download from libssh2.org.


 Building the library
 --------------------

 To avoid all kinds of misunderstandings caused by firewalls thinking that
 a .com file must be an MS-DOS executable, all command procedures are called
 .dcl.

 Go to the vms subdirectory in the download tree, and issue the following
 command:

 @libssh2_make_lib.dcl

 This should produce libssh2_x_y_z.exe in this same vms directory.


 Building the examples
 ---------------------

 A number of examples are also part of the full libssh2 delivery.
 You can compile and link them either against the object library
 produced when building the shared image, or against the shared image
 produced in the step before.

 You can compile only one of the examples by giving only the
 name part of the filename of the example as p1 to the
 build procedure:

 @libssh2_make_example.dcl

 or for instance

 @libssh2_make_example.dcl sftp

 By default, libssh2_make_example.dcl links to the object libraries
 produced by the libssh2_make_lib.dcl procedure. If you want to link
 against the shared image library made in the same procedure, invoke
 the procedure like so:

 @libssh2_make_example.dcl sftp "SHARED"

 The procdure defines a process logical gnv$libssh2 pointing to the shared
 image library in the directory, which obviously will not survive a logout.


 Building the help library
 -------------------------

 The man pages can be converted to a VMS help library by issuing
 this command :

 @libssh2_make_help.dcl

 It uses a simple but fairly effective c program man2help.c
 to achieve this.

 Building a PCSI kit
 -------------------

 When you have built the shared library and the help library,
 you can build a PCSI kit by issueing this command:

 @libssh2_make_kit.dcl
	*These are the porting notes to OpenVMS, as of 7 April 2010
	by Jose Baars. This file will be installed as
	libssh2*.release_notes by the product install kit.


	LIBSSH2
	-------

	LIBSSH2 is a client-side library written in C that aims to
	implement the SSH2 protocol. It is an open source project,
	to be found at http://libssh2.org.

	GNV
	---

	The library uses the GNV prefix, on advise of the kind supporter
	of the GNV project, John Malmberg.

	Installing the PCSI kit
	=======================

	Prerequisites
	-------------
	- VMS version 8.3 minimal.
	See the remarks at prerequisites for building the kit
	- TCP/IP stack, both TCP/IP services and Multinet should work.
	See the remarks at prerequisites for building the kit
	- HP OPENSSL V1.3 minimal.
	See the remarks at prerequisites for building the kit
	- JEM ZLIB V1.2-3E1 minimal.
	See the remarks at prerequisites for building the kit

	The first three dependencies are tested at installation time, and
	installation will fail if any these products are not installed.
	The ZLIB dependency is not tested by the product installation
	procedure, as libssh2 will probably be installed as part of
	multiple libraries including zlib.

	Install
	-------


	The kit will install gnv$libssh2.exe in a directory tree that might
	already be available on your system if you have installed other gnv*
	libraries or utilities.

	The directory tree for gnv$libssh2.exe will be like this:

	[gnv] -- [usr] -- [include] -- [libssh2] include files for libssh2
	[lib] gnv$libssh2_x_y_z.exe
	[share] -- [doc] -- [libssh2] libssh2.hlb,
	release notes (this file),
	libssh2 release notes

	optional:
	[example] libssh2_examples-x_y_z.bck
	[common_src] libssh2-x_y_z_src.bck

	By default, it will install the shared image and include files to
	SYS$COMMON:[GNV...].

	You can override this destination by specifying the destination
	directory after /DESTINATION= on the product install command line.
	This is particularly of use when installing the library on a cluster
	without a common system disk.

	Please ignore the following warnings, as the kit is not signed :

	%PCSI-I-CANNOTVAL, cannot validate dev:[dir]JCB-AXPVMS-LIBSSH2-V0102-05D20100402-1.PCSI
	-PCSI-I-NOTSIGNED, product kit is not signed and therefore has no manifest file

	Optionally, you can install a backup saveset with some programming examples,
	or a backupo saveset with the complete libssh2 source tree.

	you will need to answer 'NO' to the question
	'Do you want the default for all options'.

	and 'YES' to either or both the following questions:

	Do you want the libssh2 C programming examples ? [NO]

	Do you want the complete libssh2 source tree ? [NO]


	Post installation tasks
	-----------------------

	Although we will try to maintain upward compatibility of libssh2,
	this can not be guaranteed by the libssh2 project itself for OpenVMS,
	nor eternally by us.

	To use libssh2 effectively, you will have to define a system logical
	to point to the shared image. If you are willing to take the gamble,
	define this logical in your systartup like so:

	$ define/system/executive gnv$libssh2 dev:[dir..]gnv$libssh2_x_y_z.exe

	Optionally, you can install the executbale like so:

	$ mc sysgen install dev:[dir..]gnv$libssh2_x_y_z.exe/open/share/header

	Link your programs against gnv$libssh2, and when upgrading libssh2
	test thoroughly.

	If you want to be extra cautious define a system logical like this:

	$ define/system/executive gnv$libssh2_x_y_z dev:[dir..]gnv$libssh2_x_y_z.exe

	Link programs against gnv$libssh2_x_y_z, and when upgrading libssh2
	link against new versions.

	It is probably more convenient in the last case to link against the object
	library provided in the source backup saveset. Both an uppercase and a
	mixed case object library, called libssh2.olb and libssh2_asis.olb
	are provided.


	Compiling and linking against libssh2
	-------------------------------------

	The shared image library has a vector table with both uppercase and
	mixed case entry points, allowing to link directly against the shared
	image wether you need the /NAMES=AS_IS or not.

	To link successfully, you MUST use /NAMES=shortened, as some function
	names in libssh2 are longer than the VMS maximum of 32 characters.

	If you chose to install the examples, you can unpack the backup
	saveset by

	backup/sel=*.c device:[gnv.usr.share.doc.libssh2.examples]libssh2_examples-x_y_z.bck -
	[]

	They can by compiled and linked by these commands ( provided you have defined
	the gnv$libssh2 logical) :

	$ cc/include=dev:[gnv.usr.include.libssh2] xxx.c/names=shortened
	$ link/opt=sys$input: xxx.obj
	gnv$libssh2/share




	Building gnv$libssh2
	====================

	You can build gnv$libssh2 yourself, which may have advantages, as the library is
	in full development, very regularly new features are added.

	For production use, it is probably advisable to use a stable version, and
	link against that. To check out new features, statically linking against
	the object library is probably more practical, to avoid compatibility
	issues.


	Prerequisites
	-------------

	You will need to have the following available:

	- An Alpha or Itanium VMS system. Due to dependencies on zlib, ssl and ODS-5,
	support on VAXen would be cumbersome at least.

	- VMS version 8.3 minimal. This is a requirement of gnv$zlibshr.exe against
	which shared image library libssh2 is linked. If you use another zlib
	to link against, you can make it work under lower versions of VMS.
	I have made it work on VMS 7.3-2 with not a lot of difficulty.
	Also, if you are not interested in compression, you can choose not
	to link against zlib at all; in that case comment out the
	#define LIBSSH2_HAVE_ZLIB in libssh2_config.h.

	- TCP/IP services or Multinet for OpenVMS.
	TCPWare has not been tested.

	- The HP OpenSSL product. Of course, with tweaking, you can probably link
	it against the OpenSSL library, but that is not what I have used.

	- A C compiler. I don't know any other working C compilers than
	the DEC/Compac/HP-C compiler on VMS.

	- An ODS-5 disk. With tweaking you'll get it to work on an ODS-2
	disk, but it is unpractical to do so.

	- A version of VMSTAR that understands ODS-5 disks and extended
	filenames. Look here:
	http://ftp.process.com/ftp/vms-freeware/fileserv/vmstar.zip

	- gunzip, available for instance at Steven M Schweda's website:
	http://antinode.info/ftp/gzip/gzip-1_3_12b_vms/gzip-1_3_12b_vms.zip

	Optional:

	- curl, to be found at http://curl.haxx.se
	You might want to use curl to download the libssh2 kit directly
	to you VMS machine. Interestingly, sftp in curl is implemented using
	libssh2, soon to be expected on VMS as well, hopefully.

	Downloading libssh2
	-------------------

	At the website of libssh2, you can find stable and daily gzipped
	tarballs. if you have a computer connected to internet you can
	download a daily build yourself by a procedure that looks a lot like
	this ( fill out your own proxy user/password, set up right symbols to
	gunzip, vmstar and curl and set up the libssh2 build version):

	$ libssh2_version = "1.2.6"
	$!
	$ proxy_line = " ""-U"" ""''proxy_userpass'"" ""-x"" ""''proxy_hostport'"" "
	$!
	$ currentday = f$cvtime(,,"date") - "-" - "-"
	$!
	$ set def mydev:[mydir.libssh2]
	$!
	$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.gz") .nes. ""
	$ then
	$ delete libssh2-'libssh2_version'-'currentday'.tar.gz;*
	$ endif
	$!
	$ curl 'proxy_line' "http://libssh2.org/snapshots/libssh2-''libssh2_version'-''currentday'.tar.gz" -
	-o libssh2-'libssh2_version'-'currentday'.tar.gz
	$!
	$!
	$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.;") .nes. ""
	$ then
	$ delete libssh2-'libssh2_version'-'currentday'.tar.;*
	$ endif
	$!
	$ gunzip libssh2-'libssh2_version'-'currentday'.tar.gz
	$!
	$ tarfile = f$search("libssh2-''libssh2_version'-''currentday'.tar.;")
	$ vmstar xf 'tarfile'

	Downloading a stable build will need you to get rid of the currentday.

	After the download, you should have a directory tree with a toplevel
	directory called [libssh2-x.y.z-yyyymmdd].
	One of the subdirectories is called vms.

	Getting the libssh2 sources from the source backup in the binary kit
	--------------------------------------------------------------------

	During installation of the binary kit, you are given the option
	of installing the sources. If chosen, a backup saveset with
	the complete libssh2 directory is made available in
	[gnv.common_src].

	By restoring this backup saveset, you end up with the same
	set of files as by the direct download from libssh2.org.


	Building the library
	--------------------

	To avoid all kinds of misunderstandings caused by firewalls thinking that
	a .com file must be an MS-DOS executable, all command procedures are called
	.dcl.

	Go to the vms subdirectory in the download tree, and issue the following
	command:

	@libssh2_make_lib.dcl

	This should produce libssh2_x_y_z.exe in this same vms directory.



	Building the examples
	---------------------

	A number of examples are also part of the full libssh2 delivery.
	You can compile and link them either against the object library
	produced when building the shared image, or against the shared image
	produced in the step before.

	You can compile only one of the examples by giving only the
	name part of the filename of the example as p1 to the
	build procedure:

	@libssh2_make_example.dcl

	or for instance

	@libssh2_make_example.dcl sftp

	By default, libssh2_make_example.dcl links to the object libraries
	produced by the libssh2_make_lib.dcl procedure. If you want to link
	against the shared image library made in the same procedure, invoke
	the procedure like so:

	@libssh2_make_example.dcl sftp "SHARED"

	The procdure defines a process logical gnv$libssh2 pointing to the shared
	image library in the directory, which obviously will not survive a logout.


	Building the help library
	-------------------------

	The man pages can be converted to a VMS help library by issuing
	this command :

	@libssh2_make_help.dcl

	It uses a simple but fairly effective c program man2help.c
	to achieve this.

	Building a PCSI kit
	-------------------

	When you have built the shared library and the help library,
	you can build a PCSI kit by issueing this command:

	@libssh2_make_kit.dcl