Debian Codegraph @

vms/readme.vms

raw
1 *These are the porting notes to OpenVMS, as of 7 April 2010
2 by Jose Baars. This file will be installed as
3 libssh2*.release_notes by the product install kit.
4
5
6 LIBSSH2
7 -------
8
9 LIBSSH2 is a client-side library written in C that aims to
10 implement the SSH2 protocol. It is an open source project,
11 to be found at https://libssh2.org.
12
13 GNV
14 ---
15
16 The library uses the GNV prefix, on advise of the kind supporter
17 of the GNV project, John Malmberg.
18
19 Installing the PCSI kit
20 =======================
21
22 Prerequisites
23 -------------
24 - VMS version 8.3 minimal.
25 See the remarks at prerequisites for building the kit
26 - TCP/IP stack, both TCP/IP services and Multinet should work.
27 See the remarks at prerequisites for building the kit
28 - HP OPENSSL V1.3 minimal.
29 See the remarks at prerequisites for building the kit
30 - JEM ZLIB V1.2-3E1 minimal.
31 See the remarks at prerequisites for building the kit
32
33 The first three dependencies are tested at installation time, and
34 installation will fail if any these products are not installed.
35 The ZLIB dependency is not tested by the product installation
36 procedure, as libssh2 will probably be installed as part of
37 multiple libraries including zlib.
38
39 Install
40 -------
41
42
43 The kit will install gnv$libssh2.exe in a directory tree that might
44 already be available on your system if you have installed other gnv*
45 libraries or utilities.
46
47 The directory tree for gnv$libssh2.exe will be like this:
48
49 [gnv] -- [usr] -- [include] -- [libssh2] include files for libssh2
50 [lib] gnv$libssh2_x_y_z.exe
51 [share] -- [doc] -- [libssh2] libssh2.hlb,
52 release notes (this file),
53 libssh2 release notes
54
55 optional:
56 [example] libssh2_examples-x_y_z.bck
57 [common_src] libssh2-x_y_z_src.bck
58
59 By default, it will install the shared image and include files to
60 SYS$COMMON:[GNV...].
61
62 You can override this destination by specifying the destination
63 directory after /DESTINATION= on the product install command line.
64 This is particularly of use when installing the library on a cluster
65 without a common system disk.
66
67 Please ignore the following warnings, as the kit is not signed :
68
69 %PCSI-I-CANNOTVAL, cannot validate dev:[dir]JCB-AXPVMS-LIBSSH2-V0102-05D20100402-1.PCSI
70 -PCSI-I-NOTSIGNED, product kit is not signed and therefore has no manifest file
71
72 Optionally, you can install a backup saveset with some programming examples,
73 or a backupo saveset with the complete libssh2 source tree.
74
75 you will need to answer 'NO' to the question
76 'Do you want the default for all options'.
77
78 and 'YES' to either or both the following questions:
79
80 Do you want the libssh2 C programming examples ? [NO]
81
82 Do you want the complete libssh2 source tree ? [NO]
83
84
85 Post installation tasks
86 -----------------------
87
88 Although we will try to maintain upward compatibility of libssh2,
89 this can not be guaranteed by the libssh2 project itself for OpenVMS,
90 nor eternally by us.
91
92 To use libssh2 effectively, you will have to define a system logical
93 to point to the shared image. If you are willing to take the gamble,
94 define this logical in your systartup like so:
95
96 $ define/system/executive gnv$libssh2 dev:[dir..]gnv$libssh2_x_y_z.exe
97
98 Optionally, you can install the executable like so:
99
100 $ mc sysgen install dev:[dir..]gnv$libssh2_x_y_z.exe/open/share/header
101
102 Link your programs against gnv$libssh2, and when upgrading libssh2
103 test thoroughly.
104
105 If you want to be extra cautious define a system logical like this:
106
107 $ define/system/executive gnv$libssh2_x_y_z dev:[dir..]gnv$libssh2_x_y_z.exe
108
109 Link programs against gnv$libssh2_x_y_z, and when upgrading libssh2
110 link against new versions.
111
112 It is probably more convenient in the last case to link against the object
113 library provided in the source backup saveset. Both an uppercase and a
114 mixed case object library, called libssh2.olb and libssh2_asis.olb
115 are provided.
116
117
118 Compiling and linking against libssh2
119 -------------------------------------
120
121 The shared image library has a vector table with both uppercase and
122 mixed case entry points, allowing to link directly against the shared
123 image whether you need the /NAMES=AS_IS or not.
124
125 To link successfully, you MUST use /NAMES=shortened, as some function
126 names in libssh2 are longer than the VMS maximum of 32 characters.
127
128 If you chose to install the examples, you can unpack the backup
129 saveset by
130
131 backup/sel=*.c device:[gnv.usr.share.doc.libssh2.examples]libssh2_examples-x_y_z.bck -
132 []
133
134 They can by compiled and linked by these commands ( provided you have defined
135 the gnv$libssh2 logical) :
136
137 $ cc/include=dev:[gnv.usr.include.libssh2] xxx.c/names=shortened
138 $ link/opt=sys$input: xxx.obj
139 gnv$libssh2/share
140
141
142
143
144 Building gnv$libssh2
145 ====================
146
147 You can build gnv$libssh2 yourself, which may have advantages, as the library is
148 in full development, very regularly new features are added.
149
150 For production use, it is probably advisable to use a stable version, and
151 link against that. To check out new features, statically linking against
152 the object library is probably more practical, to avoid compatibility
153 issues.
154
155
156 Prerequisites
157 -------------
158
159 You will need to have the following available:
160
161 - An Alpha or Itanium VMS system. Due to dependencies on zlib, ssl and ODS-5,
162 support on VAXen would be cumbersome at least.
163
164 - VMS version 8.3 minimal. This is a requirement of gnv$zlibshr.exe against
165 which shared image library libssh2 is linked. If you use another zlib
166 to link against, you can make it work under lower versions of VMS.
167 I have made it work on VMS 7.3-2 with not a lot of difficulty.
168 Also, if you are not interested in compression, you can choose not
169 to link against zlib at all; in that case comment out the
170 #define LIBSSH2_HAVE_ZLIB in libssh2_config.h.
171
172 - TCP/IP services or Multinet for OpenVMS.
173 TCPWare has not been tested.
174
175 - The HP OpenSSL product. Of course, with tweaking, you can probably link
176 it against the OpenSSL library, but that is not what I have used.
177
178 - A C compiler. I don't know any other working C compilers than
179 the DEC/Compac/HP-C compiler on VMS.
180
181 - An ODS-5 disk. With tweaking you'll get it to work on an ODS-2
182 disk, but it is unpractical to do so.
183
184 - A version of VMSTAR that understands ODS-5 disks and extended
185 filenames. Look here:
186 http://ftp.process.com/ftp/vms-freeware/fileserv/vmstar.zip
187
188 - gunzip, available for instance at Steven M Schweda's website:
189 http://antinode.info/ftp/gzip/gzip-1_3_12b_vms/gzip-1_3_12b_vms.zip
190
191 Optional:
192
193 - curl, to be found at https://curl.haxx.se
194 You might want to use curl to download the libssh2 kit directly
195 to you VMS machine. Interestingly, sftp in curl is implemented using
196 libssh2, soon to be expected on VMS as well, hopefully.
197
198 Downloading libssh2
199 -------------------
200
201 At the website of libssh2, you can find stable and daily gzipped
202 tarballs. if you have a computer connected to internet you can
203 download a daily build yourself by a procedure that looks a lot like
204 this ( fill out your own proxy user/password, set up right symbols to
205 gunzip, vmstar and curl and set up the libssh2 build version):
206
207 $ libssh2_version = "1.2.6"
208 $!
209 $ proxy_line = " ""-U"" ""''proxy_userpass'"" ""-x"" ""''proxy_hostport'"" "
210 $!
211 $ currentday = f$cvtime(,,"date") - "-" - "-"
212 $!
213 $ set def mydev:[mydir.libssh2]
214 $!
215 $ if f$search("libssh2-''libssh2_version'-''currentday'.tar.gz") .nes. ""
216 $ then
217 $ delete libssh2-'libssh2_version'-'currentday'.tar.gz;*
218 $ endif
219 $!
220 $ curl 'proxy_line' "https://libssh2.org/snapshots/libssh2-''libssh2_version'-''currentday'.tar.gz" -
221 -o libssh2-'libssh2_version'-'currentday'.tar.gz
222 $!
223 $!
224 $ if f$search("libssh2-''libssh2_version'-''currentday'.tar.;") .nes. ""
225 $ then
226 $ delete libssh2-'libssh2_version'-'currentday'.tar.;*
227 $ endif
228 $!
229 $ gunzip libssh2-'libssh2_version'-'currentday'.tar.gz
230 $!
231 $ tarfile = f$search("libssh2-''libssh2_version'-''currentday'.tar.;")
232 $ vmstar xf 'tarfile'
233
234 Downloading a stable build will need you to get rid of the currentday.
235
236 After the download, you should have a directory tree with a toplevel
237 directory called [libssh2-x.y.z-yyyymmdd].
238 One of the subdirectories is called vms.
239
240 Getting the libssh2 sources from the source backup in the binary kit
241 --------------------------------------------------------------------
242
243 During installation of the binary kit, you are given the option
244 of installing the sources. If chosen, a backup saveset with
245 the complete libssh2 directory is made available in
246 [gnv.common_src].
247
248 By restoring this backup saveset, you end up with the same
249 set of files as by the direct download from libssh2.org.
250
251
252 Building the library
253 --------------------
254
255 To avoid all kinds of misunderstandings caused by firewalls thinking that
256 a .com file must be an MS-DOS executable, all command procedures are called
257 .dcl.
258
259 Go to the vms subdirectory in the download tree, and issue the following
260 command:
261
262 @libssh2_make_lib.dcl
263
264 This should produce libssh2_x_y_z.exe in this same vms directory.
265
266
267
268 Building the examples
269 ---------------------
270
271 A number of examples are also part of the full libssh2 delivery.
272 You can compile and link them either against the object library
273 produced when building the shared image, or against the shared image
274 produced in the step before.
275
276 You can compile only one of the examples by giving only the
277 name part of the filename of the example as p1 to the
278 build procedure:
279
280 @libssh2_make_example.dcl
281
282 or for instance
283
284 @libssh2_make_example.dcl sftp
285
286 By default, libssh2_make_example.dcl links to the object libraries
287 produced by the libssh2_make_lib.dcl procedure. If you want to link
288 against the shared image library made in the same procedure, invoke
289 the procedure like so:
290
291 @libssh2_make_example.dcl sftp "SHARED"
292
293 The procedure defines a process logical gnv$libssh2 pointing to the shared
294 image library in the directory, which obviously will not survive a logout.
295
296
297 Building the help library
298 -------------------------
299
300 The man pages can be converted to a VMS help library by issuing
301 this command :
302
303 @libssh2_make_help.dcl
304
305 It uses a simple but fairly effective c program man2help.c
306 to achieve this.
307
308 Building a PCSI kit
309 -------------------
310
311 When you have built the shared library and the help library,
312 you can build a PCSI kit by issuing this command:
313
314 @libssh2_make_kit.dcl