Merge branch 'vim-with-runtime' into feat/rel-line-numbers
[vim_extended.git] / src / INSTALLvms.txt
blobc617aae4a33771083d0a7548f89458e9364547fb
1 INSTALLvms.txt - Installation of Vim on OpenVMS
3 Maintainer:   Zoltan Arpadffy <arpadffy@polarhome.com>
4 Last change:  2008 Jan 06
6 This file contains instructions for compiling Vim on Openvms.
7 If you already have an executable version of Vim, you don't need this.
9 If you skip settings described here, then you will get the default Vim
10 behavior as it is documented, which should be fine for most users.
12 The file "feature.h" can be edited to match your preferences, but this files
13 does not describe possibilities hidden in feature.h acrobatics, however
14 parameters from MAKE_VMS.MMS actively uses and sets up parameters in relation
15 with feature.h
17 More information and case analysis you can found in os_vms.txt
18 ([runtime.doc]os_vms.txt or :help vms from vim prompt)
20 Contents:
21 1. Download files
22 2. Configuration
23 3. Compilation DECC
24 4. Compilation VAXC
25 5. CTAGS, XXD
26 6. Deployment
27 7. GTK and other features
28 8. Notes
29 9. Authors
31 ----------------------------------------------------------------------------
32 1. Download files
34 1.1. Visit the Vim ftp site (see ftp://ftp.vim.org/pub/vim/MIRRORS)
35      and obtain the following three files:
37      unix/vim-X.X-src.tar.gz
38      unix/vim-X.X-rt.tar.gz
39      extra/vim-X.X-extra.tar.gz
41      where X.X is the version number.
43 1.2. Expand the three archives.
45 1.3. Apply patches if they exist.  (Patch files are found in the ftp
46      site in the "patches" directory.)
48 1.4. You will need either the DECSET mms utility or the freely available clone
49      of it called mmk (VMS has no make utility in the standard distribution).
50      You can download mmk from http://www.openvms.digital.com/freeware/MMK/
52 1.5. If you want to have Perl, Python or Tcl support in Vim you will need VMS
53      distributions for them as well.
55 1.6  If you want to have GTK executable, you need to have properly installed
56      GTK libraries.
58 NOTE: procedure in chapter 1 describes source code preparation from multi OS
59 code, however it is available OpenVMS optimized (and tested) source code from:
60 ftp://ftp.polarhome.com/pub/vim/source/vms/
61 (http://www.polarhome.com/vim/files/source/vms/)
63 Current OpenVMS source code as .zip or .tar.gz file is possible to download
64 from CVS mirror ftp://ftp.polarhome.com/pub/cvs/SOURCE/
65 (http://www.polarhome.com/cvs/SOURCE/)
67 2.   Configuration
69 2.1. Edit vim-X.X/src/feature.h for your preference.  (You can skip
70      this, then you will get the default behavior as is documented,
71      which should be fine for most people.)
73      For example, if you want to add the MULTI_BYTE feature, turn on
74      #define MULTI_BYTE
76 2.2  Edit vim-X.X/src/Make_vms.mms to customize your Vim. Options are:
78         Parameter name  : MODEL
79         Description     : Build model selection
80         Options:        : TINY    - Almost no features enabled, not even
81                           multiple windows
82                           SMALL   - Few features enabled, as basic as possible
83                           NORMAL  - A default selection of features enabled
84                           BIG     - Many features enabled, as rich as possible.
85                           (OpenVMS default)
86                           HUGE    - All possible features enabled.
87                           Uncommented - will default to BIG
88         Default         : MODEL = BIG
90         Parameter name  : GUI
91         Description     : GUI or terminal mode executable
92         Options:        : YES - GUI executable
93                           Uncommented - char only
94         Default         : GUI = YES
96         Parameter name  : GTK
97         Description     : Enable GTK in GUI mode.
98                           It enables features as toolbar etc.
99         Options:        : YES - GTK executable
100                           Uncommented - without GTK
101         Default         : Uncommented
103         Parameter name  : XPM
104         Description     : Enable XPM libraries in GUI/Motif mode.
105                           It enables features as toolbar etc.
106         Options:        : YES - GUI executable
107                           Uncommented - without XPM
108         Default         : Uncommented
110         Parameter name  : DECC
111         Description     : Compiler selection
112         Options:        : YES - DECC compiler
113                           Uncommented - VAXC compiler
114         Default         : DECC = YES
116         Parameter name  : CCVER
117         Description     : Compiler version with :ver command
118         Options:        : YES - Compiler version info will be added
119                           Uncommented - will not be added
120         Default         : CCVER = YES
122         Parameter name  : DEBUG
123         Description     : Building a debug version
124         Options:        : YES - debug version will be built
125                           Uncommented - building normal executable
126         Default         : Uncommented
128         Parameter name  : VIM_TCL
129         Description     : Add Tcl support
130         Options:        : YES - Build with support
131                           Uncommented - build without support.
132         Default         : Uncommented
134         Parameter name  : VIM_PERL
135         Description     : Add Perl support
136         Options:        : YES - Build with support
137                           Uncommented - build without support.
138         Default         : Uncommented
140         Parameter name  : VIM_PYTHON
141         Description     : Add Python support
142         Options:        : YES - Build with support
143                           Uncommented - build without support.
144         Default         : Uncommented
146         Parameter name  : VIM_XIM
147         Description     : X Input Method. For entering special languages
148                           like chinese and Japanese. Please define just
149                           one: VIM_XIM or VIM_HANGULIN
150         Options:        : YES - Build with support
151                           Uncommented - build without support.
152         Default         : Uncommented
154         Parameter name  : VIM_HANGULIN
155         Description     : Internal Hangul input method. GUI only.
156                           Please define just one: VIM_XIM or VIM_HANGULIN
157         Options:        : YES - Build with support
158                           Uncommented - build without support.
159         Default         : Uncommented
161         Parameter name  : VIM_TAG_ANYWHITE
162         Description     : Allow any white space to separate the fields in a
163                           tags file
164                           When not defined, only a TAB is allowed.
165         Options:        : YES - Build with support
166                           Uncommented - build without support.
167         Default         : Uncommented
169      You can edit the *_INC and *_LIB qualifiers, but it is really
170      not recommended for beginners.
172 3. Compilation DECC
174 3.1. If you have MSS on your system, the command
176         mms /descrip=Make_vms.mms
178      will start building your own customized version of Vim.
179      The adequate command for mmk is:
181         mmk /descrip=Make_vms.mms
183      NOTE: Because of empty /auto/config.h (needed for Unix configure) build
184      will fail with very strange messages. Therefore before building, it is
185      recommended to make one clean up, to prepare everything for OpenVMS
186      development. The command is:
188         mms /descrip=Make_vms.mms clean
190 4. Compilation VAXC
192 4.1. VAXC compiler is not fully ANSI C compatible in pre-processor directives
193      semantics, therefore you have to use a converter program what will do the
194      lion part of the job.
196         @os_vms_fix.com *.c *.h <.proto>*.pro
198      more information can be found in os_vms_fix.com file itself.
200      NOTE: even if os_vms_fix.com will fix all pre-processor directives it will
201      leave singe (long) line directives. You have to fix them manually.
202      Known problematic files are option.h and option.c
204 4.2. After the conversion you can continue building as it has been described
205      above.
207 5. CTAGS, XXD
209 5.1. MMS_VIM.EXE is building together with VIM.EXE, but for CTAGS.EXE and
210      XXD.EXE you should change to subdirectory <.CTAGS> or <.XXD> and build
211      them separately.
213 5.2. In these directories you can found one make file for VMS as well.
214      Please read the detailed build instructions in the related *.MMS file.
216 6.   Deployment
218 6.1. Copy over all executables to the deployment directory.
220 6.2. Vim uses a special directory structure to hold the document and runtime
221      files:
223    vim (or wherever)
224     |-- doc
225     |-- syntax
226     vimrc    (system rc files)
227     gvimrc
229 6.3 Define logicals VIM
231         define/nolog VIM device:[leading-path-here.vim]
233      to get vim.exe to find its document, filetype, and syntax files.
235      Now, if you are lucky you should have one own built, customized and
236      working Vim.
238 7.   GTK and other features
240 7.1  General notes
242      To be able to build external GUI or language support wyo have to enable
243      related feature in MAKE_VMS.MMS file. Usually it need some extra tuning
244      around include files, shared libraries etc.
246      Please note, that leading "," are valuable for MMS/MMK syntax.
248      MAKE_VMS.MMS uses defines as described below:
250 7.1.1   feature_DEF = ,"SOME_FEATURE"
252      Submits definition to compiler preprocessor to enable code blocks
253      defined with
254      #ifdef SOME_FEATURE
255      {some code here}
256      #endif
258      Example:  TCL_DEF = ,"FEAT_TCL"
261 7.1.2   feature_SRC = code1.c code2.c
263      Defines source code related with particular feature.
264      Example:  TCL_SRC = if_tcl.c
266 7.1.3   feature_OBJ = code1.obj code2.obj
268      Lists objects created from source codes listed in feature_SRC
269      Example: PERL_OBJ = if_perlsfio.obj if_perl.obj
271 7.1.4  feature_LIB = ,OS_VMS_TCL.OPT/OPT
273      Defines the libraries that have to be used for build.
274      If it is an OPT file then MAKE_VMS.MMS creates OPT files
275      in gen_feature procedure.
277      Example:
278      PERL_LIB = ,OS_VMS_PERL.OPT/OPT
280 .IFDEF VIM_PERL
281 perl_env :
282         -@ write sys$output "creating OS_VMS_PERL.OPT file."
283         -@ open/write opt_file OS_VMS_PERL.OPT
284         -@ write opt_file "PERLSHR /share"
285         -@ close opt_file
286 .ELSE
287 perl_env :
288         -@ !
289 .ENDIF
292 7.1.5  feature_INC = ,dka0:[tcl80.generic]
294      Defines the directory where the necessary include files are.
295      Example: TCL_INC = ,dka0:[tcl80.generic]
297 7.2  GTK
299      To build VIM with GTK you have to install GTK on your OpenVMS.
300      So far it works just on Alpha and IA64. More information at:
301      http://www.openvms.compaq.com/openvms/products/ips/gtk.html
303      You need also the OpenVMS Porting Library:
304      http://www.openvms.compaq.com/openvms/products/ips/porting.html
306      Source code for GTK and porting library that is used to build
307      VMS executables at polarhome.com are at
308      http://www.polarhome.com/vim/files/source/vms/
310      Enable GTK in make_vms.mms file with GTK = YES
311      Define GTK_ROOT that points to your GTK root directory.
313      You will need to edit GTKDIR variable in order to point
314      to GTK header files and libraries.
316      GTK_DIR  = ALPHA$DKA0:[GTK128.]
318      ".]" at the end is very important.
320      Build it as normally.
322      Used sharable images are:
323         gtk_root:[glib]libglib.exe /share,-
324         gtk_root:[glib.gmodule]libgmodule.exe /share,-
325         gtk_root:[gtk.gdk]libgdk.exe /share,-
326         gtk_root:[gtk.gtk]libgtk.exe /share
328      During runtime it is suggested to have all these files installed and
329      copied to SYS$LIBRARY: to be able to use it without problems.
330      Also VMS_JACKETS.EXE from OpenVMS Porting Library.
332      Please note, that GTK uses /name=(as_is,short)/float=ieee/ieee=denorm
333      complier directives that is not compatible with "standard" VMS usage,
334      therefore other external features might fail as PERL, PYTHON and TCL
335      support.
337 7.3  PERL
339      You have to install OpenVMS perl package from:
340      http://www.openvms.compaq.com/openvms/products/ips/apache/csws_perl_relnotes.html or build on your own from sources downloaded from http://www.perl.org
342      You need defined PERLSHR logical that points to PERL shareable image
343      (or you can just copy over to SYS$LIBRARY:)
345      Enable Perl feature at make_vms.mms with VIM_PERL = YES
347      Edit PERL_INC = to point to perl includes directory where is extern.h
349      Build as usually.
351 7.4  PYTHON
353      You have to install an OpenVMS python package.
354      Set up the normal Python work environment.
356      You have to have defined PYTHON_INCLUDE and PYTHON_OLB logicals.
357      PYTHON_INCLUDE should point to Python include files where for ex:
358      python.h is located.
359      Enable Python feature at make_vms.mms with VIM_PYTHON = YES
361      Build as usually.
363 7.5  TCL
365      You have to install an OpenVMS TCL package.
366      Set up the normal TCL work environment.
368      You have to have defined TCLSHR logical that points to shareable image.
370      Enable TCL feature at make_vms.mms with VIM_TCL = YES
372      Edit TCL_INC = to point to TCL includes directory where is tcl.h
374      Build as usually.
376 8.   Notes
378 8.1. New Compaq C compiler
380      If you are using Compaq C compiler V6.2 or newer, Informational messages
381      of the type QUESTCOMPARE will be displayed. You should ignore those
382      messages ; they are generated only because some test comparisons are done
383      with variables which type vary depending on the OS. Under VMS, those are
384      "unsigned" and the compiler issue a message whenever the comparison is
385      done with '<=' to 0. However, the code is correct and will behave as
386      expected.
387      ( Jerome Lauret <JLAURET@mail.chem.sunysb.edu> Vim 6.0n )
388         NOTE: from version 6.0ad Vim code has been reviewed and these warnings
389         have been corrected.
391 9.   Authors
393      Initial version, 2000 Jul 19, Zoltan Arpadffy <arpadffy@polarhome.com>