summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_90.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/usr_90.txt')
-rw-r--r--runtime/doc/usr_90.txt478
1 files changed, 478 insertions, 0 deletions
diff --git a/runtime/doc/usr_90.txt b/runtime/doc/usr_90.txt
new file mode 100644
index 0000000..418f1f0
--- /dev/null
+++ b/runtime/doc/usr_90.txt
@@ -0,0 +1,478 @@
+*usr_90.txt* For Vim version 9.1. Last change: 2022 May 13
+
+ VIM USER MANUAL - by Bram Moolenaar
+
+ Installing Vim
+
+ *install*
+Before you can use Vim you have to install it. Depending on your system it's
+simple or easy. This chapter gives a few hints and also explains how
+upgrading to a new version is done.
+
+|90.1| Unix
+|90.2| MS-Windows
+|90.3| Upgrading
+|90.4| Common installation issues
+|90.5| Uninstalling Vim
+
+ Previous chapter: |usr_52.txt| Write plugins using Vim9 script
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*90.1* Unix
+
+First you have to decide if you are going to install Vim system-wide or for a
+single user. The installation is almost the same, but the directory where Vim
+is installed in differs.
+ For a system-wide installation the base directory "/usr/local" is often
+used. But this may be different for your system. Try finding out where other
+packages are installed.
+ When installing for a single user, you can use your home directory as the
+base. The files will be placed in subdirectories like "bin" and "shared/vim".
+
+
+FROM A PACKAGE
+
+You can get precompiled binaries for many different UNIX systems. There is a
+long list with links on this page:
+
+ http://www.vim.org/binaries.html ~
+
+Volunteers maintain the binaries, so they are often out of date. It is a
+good idea to compile your own UNIX version from the source. Also, creating
+the editor from the source allows you to control which features are compiled.
+This does require a compiler though.
+
+If you have a Linux distribution, the "vi" program is probably a minimal
+version of Vim. It doesn't do syntax highlighting, for example. Try finding
+another Vim package in your distribution, or search on the web site.
+
+
+FROM SOURCES
+
+To compile and install Vim, you will need the following:
+
+ - A C compiler (GCC preferred)
+ - The GZIP program (you can get it from www.gnu.org)
+ - The Vim source and runtime archives
+
+To get the Vim archives, look in this file for a mirror near you, this should
+provide the fastest download:
+
+ ftp://ftp.vim.org/pub/vim/MIRRORS ~
+
+Or use the home site ftp.vim.org, if you think it's fast enough. Go to the
+"unix" directory and you'll find a list of files there. The version number is
+embedded in the file name. You will want to get the most recent version.
+ You can get the files for Unix in one big archive that contains everything:
+
+ vim-8.2.tar.bz2 ~
+
+You need the bzip2 program to uncompress it.
+
+
+COMPILING
+
+First create a top directory to work in, for example: >
+
+ mkdir ~/vim
+ cd ~/vim
+
+Then unpack the archives there. You can unpack it like this: >
+
+ tar xf path/vim-8.2.tar.bz2
+
+If your tar command doesn't support bz2 directly: >
+
+ bzip2 -d -c path/vim-8.2.tar.bz2 | tar xf -
+
+Change "path" to where you have downloaded the file.
+If you are satisfied with getting the default features, and your environment
+is setup properly, you should be able to compile Vim with just this: >
+
+ cd vim82/src
+ make
+
+The make program will run configure and compile everything. Further on we
+will explain how to compile with different features.
+ If there are errors while compiling, carefully look at the error messages.
+There should be a hint about what went wrong. Hopefully you will be able to
+correct it. You might have to disable some features to make Vim compile.
+Look in the Makefile for specific hints for your system.
+
+
+TESTING
+
+Now you can check if compiling worked OK: >
+
+ make test
+
+This will run a sequence of test scripts to verify that Vim works as expected.
+Vim will be started many times and all kinds of text and messages flash by.
+If it is alright you will finally see:
+
+ test results: ~
+ ALL DONE ~
+
+If you get "TEST FAILURE" some test failed. If there are one or two messages
+about failed tests, Vim might still work, but not perfectly. If you see a lot
+of error messages or Vim doesn't finish until the end, there must be something
+wrong. Either try to find out yourself, or find someone who can solve it.
+You could look in the |maillist-archive| for a solution. If everything else
+fails, you could ask in the vim |maillist| if someone can help you.
+
+
+INSTALLING
+ *install-home*
+If you want to install in your home directory, edit the Makefile and search
+for a line:
+
+ #prefix = $(HOME) ~
+
+Remove the # at the start of the line.
+ When installing for the whole system, Vim has most likely already selected
+a good installation directory for you. You can also specify one, see below.
+You need to become root for the following.
+
+To install Vim do: >
+
+ make install
+
+That should move all the relevant files to the right place. Now you can try
+running vim to verify that it works. Use two simple tests to check if Vim can
+find its runtime files: >
+
+ :help
+ :syntax enable
+
+If this doesn't work, use this command to check where Vim is looking for the
+runtime files: >
+
+ :echo $VIMRUNTIME
+
+You can also start Vim with the "-V" argument to see what happens during
+startup: >
+
+ vim -V
+
+Don't forget that the user manual assumes you Vim in a certain way. After
+installing Vim, follow the instructions at |not-compatible| to make Vim work
+as assumed in this manual.
+
+
+SELECTING FEATURES
+
+Vim has many ways to select features. One of the simple ways is to edit the
+Makefile. There are many directions and examples. Often you can enable or
+disable a feature by uncommenting a line.
+ An alternative is to run "configure" separately. This allows you to
+specify configuration options manually. The disadvantage is that you have to
+figure out what exactly to type.
+ Some of the most interesting configure arguments follow. These can also be
+enabled from the Makefile.
+
+ --prefix={directory} Top directory where to install Vim.
+
+ --with-features=tiny Compile with some features disabled.
+ --with-features=normal Compile with more features enabled.
+ --with-features=huge Compile with most features enabled.
+ See |+feature-list| for which feature
+ is enabled in which case.
+
+ --enable-perlinterp Enable the Perl interface. There are
+ similar arguments for ruby, python and
+ tcl.
+
+ --disable-gui Do not compile the GUI interface.
+ --without-x Do not compile X-windows features.
+ When both of these are used, Vim will
+ not connect to the X server, which
+ makes startup faster.
+
+To see the whole list use: >
+
+ ./configure --help
+
+You can find a bit of explanation for each feature, and links for more
+information here: |feature-list|.
+ For the adventurous, edit the file "feature.h". You can also change the
+source code yourself!
+
+==============================================================================
+*90.2* MS-Windows
+
+There are two ways to install the Vim program for Microsoft Windows. You can
+uncompress several archives, or use a self-installing big archive. Most users
+with fairly recent computers will prefer the second method. For the first
+one, you will need:
+
+ - An archive with binaries for Vim.
+ - The Vim runtime archive.
+ - A program to unpack the zip files.
+
+To get the Vim archives, look in this file for a mirror near you, this should
+provide the fastest download:
+
+ ftp://ftp.vim.org/pub/vim/MIRRORS ~
+
+Or use the home site ftp.vim.org, if you think it's fast enough. Go to the
+"pc" directory and you'll find a list of files there. The version number is
+embedded in the file name. You will want to get the most recent version.
+We will use "82" here, which is version 8.2.
+
+ gvim82.exe The self-installing archive.
+
+This is all you need for the second method. Just launch the executable, and
+follow the prompts.
+
+For the first method you must choose one of the binary archives. These are
+available:
+
+ gvim82.zip The normal MS-Windows GUI version.
+ gvim82ole.zip The MS-Windows GUI version with OLE support.
+ Uses more memory, supports interfacing with
+ other OLE applications.
+ vim82w32.zip 32 bit MS-Windows console version.
+
+You only need one of them. Although you could install both a GUI and a
+console version. You always need to get the archive with runtime files.
+
+ vim82rt.zip The runtime files.
+
+Use your un-zip program to unpack the files. For example, using the "unzip"
+program: >
+
+ cd c:\
+ unzip path\gvim82.zip
+ unzip path\vim82rt.zip
+
+This will unpack the files in the directory "c:\vim\vim82". If you already
+have a "vim" directory somewhere, you will want to move to the directory just
+above it.
+ Now change to the "vim\vim82" directory and run the install program: >
+
+ install
+
+Carefully look through the messages and select the options you want to use.
+If you finally select "do it" the install program will carry out the actions
+you selected.
+ The install program doesn't move the runtime files. They remain where you
+unpacked them.
+
+In case you are not satisfied with the features included in the supplied
+binaries, you could try compiling Vim yourself. Get the source archive from
+the same location as where the binaries are. You need a compiler for which a
+makefile exists. Microsoft Visual C, MinGW and Cygwin compilers can be used.
+Check the file src/INSTALLpc.txt for hints.
+
+==============================================================================
+*90.3* Upgrading
+
+If you are running one version of Vim and want to install another, here is
+what to do.
+
+
+UNIX
+
+When you type "make install" the runtime files will be copied to a directory
+which is specific for this version. Thus they will not overwrite a previous
+version. This makes it possible to use two or more versions next to
+each other.
+ The executable "vim" will overwrite an older version. If you don't care
+about keeping the old version, running "make install" will work fine. You can
+delete the old runtime files manually. Just delete the directory with the
+version number in it and all files below it. Example: >
+
+ rm -rf /usr/local/share/vim/vim74
+
+There are normally no changed files below this directory. If you did change
+the "filetype.vim" file, for example, you better merge the changes into the
+new version before deleting it.
+
+If you are careful and want to try out the new version for a while before
+switching to it, install the new version under another name. You need to
+specify a configure argument. For example: >
+
+ ./configure --with-vim-name=vim8
+
+Before running "make install", you could use "make -n install" to check that
+no valuable existing files are overwritten.
+ When you finally decide to switch to the new version, all you need to do is
+to rename the binary to "vim". For example: >
+
+ mv /usr/local/bin/vim8 /usr/local/bin/vim
+
+
+MS-WINDOWS
+
+Upgrading is mostly equal to installing a new version. Just unpack the files
+in the same place as the previous version. A new directory will be created,
+e.g., "vim82", for the files of the new version. Your runtime files, vimrc
+file, viminfo, etc. will be left alone.
+ If you want to run the new version next to the old one, you will have to do
+some handwork. Don't run the install program, it will overwrite a few files
+of the old version. Execute the new binaries by specifying the full path.
+The program should be able to automatically find the runtime files for the
+right version. However, this won't work if you set the $VIMRUNTIME variable
+somewhere.
+ If you are satisfied with the upgrade, you can delete the files of the
+previous version. See |90.5|.
+
+==============================================================================
+*90.4* Common installation issues
+
+This section describes some of the common problems that occur when installing
+Vim and suggests some solutions. It also contains answers to many
+installation questions.
+
+
+Q: I Do Not Have Root Privileges. How Do I Install Vim? (Unix)
+
+Use the following configuration command to install Vim in a directory called
+$HOME/vim: >
+
+ ./configure --prefix=$HOME
+
+This gives you a personal copy of Vim. You need to put $HOME/bin in your
+path to execute the editor. Also see |install-home|.
+
+
+Q: The Colors Are Not Right on My Screen. (Unix)
+
+Check your terminal settings by using the following command in a shell: >
+
+ echo $TERM
+
+If the terminal type listed is not correct, fix it. For more hints, see
+|06.2|. Another solution is to always use the GUI version of Vim, called
+gvim. This avoids the need for a correct terminal setup.
+
+
+Q: My Backspace And Delete Keys Don't Work Right
+
+The definition of what key sends what code is very unclear for backspace <BS>
+and Delete <Del> keys. First of all, check your $TERM setting. If there is
+nothing wrong with it, try this: >
+
+ :set t_kb=^V<BS>
+ :set t_kD=^V<Del>
+
+In the first line you need to press CTRL-V and then hit the backspace key.
+In the second line you need to press CTRL-V and then hit the Delete key.
+You can put these lines in your vimrc file, see |05.1|. A disadvantage is
+that it won't work when you use another terminal some day. Look here for
+alternate solutions: |:fixdel|.
+
+
+Q: I Am Using RedHat Linux. Can I Use the Vim That Comes with the System?
+
+By default RedHat installs a minimal version of Vim. Check your RPM packages
+for something named "Vim-enhanced-version.rpm" and install that.
+
+
+Q: How Do I Turn Syntax Coloring On? How do I make plugins work?
+
+Use the example vimrc script. You can find an explanation on how to use it
+here: |not-compatible|.
+
+See chapter 6 for information about syntax highlighting: |usr_06.txt|.
+
+
+Q: What Is a Good vimrc File to Use?
+
+See the www.vim.org Web site for several good examples.
+
+
+Q: Where Do I Find a Good Vim Plugin?
+
+See the Vim-online site: http://vim.sf.net. Many users have uploaded useful
+Vim scripts and plugins there.
+
+
+Q: Where Do I Find More Tips?
+
+See the Vim-online site: http://vim.sf.net. There is an archive with hints
+from Vim users. You might also want to search in the |maillist-archive|.
+
+==============================================================================
+*90.5* Uninstalling Vim
+
+In the unlikely event you want to uninstall Vim completely, this is how you do
+it.
+
+
+UNIX
+
+When you installed Vim as a package, check your package manager to find out
+how to remove the package again.
+ If you installed Vim from sources you can use this command: >
+
+ make uninstall
+
+However, if you have deleted the original files or you used an archive that
+someone supplied, you can't do this. Do delete the files manually, here is an
+example for when "/usr/local" was used as the root: >
+
+ rm -rf /usr/local/share/vim/vim82
+ rm /usr/local/bin/eview
+ rm /usr/local/bin/evim
+ rm /usr/local/bin/ex
+ rm /usr/local/bin/gview
+ rm /usr/local/bin/gvim
+ rm /usr/local/bin/gvim
+ rm /usr/local/bin/gvimdiff
+ rm /usr/local/bin/rgview
+ rm /usr/local/bin/rgvim
+ rm /usr/local/bin/rview
+ rm /usr/local/bin/rvim
+ rm /usr/local/bin/rvim
+ rm /usr/local/bin/view
+ rm /usr/local/bin/vim
+ rm /usr/local/bin/vimdiff
+ rm /usr/local/bin/vimtutor
+ rm /usr/local/bin/xxd
+ rm /usr/local/man/man1/eview.1
+ rm /usr/local/man/man1/evim.1
+ rm /usr/local/man/man1/ex.1
+ rm /usr/local/man/man1/gview.1
+ rm /usr/local/man/man1/gvim.1
+ rm /usr/local/man/man1/gvimdiff.1
+ rm /usr/local/man/man1/rgview.1
+ rm /usr/local/man/man1/rgvim.1
+ rm /usr/local/man/man1/rview.1
+ rm /usr/local/man/man1/rvim.1
+ rm /usr/local/man/man1/view.1
+ rm /usr/local/man/man1/vim.1
+ rm /usr/local/man/man1/vimdiff.1
+ rm /usr/local/man/man1/vimtutor.1
+ rm /usr/local/man/man1/xxd.1
+
+
+MS-WINDOWS
+
+If you installed Vim with the self-installing archive you can run
+the "uninstall-gui" program located in the same directory as the other Vim
+programs, e.g. "c:\vim\vim82". You can also launch it from the Start menu if
+installed the Vim entries there. This will remove most of the files, menu
+entries and desktop shortcuts. Some files may remain however, as they need a
+Windows restart before being deleted.
+ You will be given the option to remove the whole "vim" directory. It
+probably contains your vimrc file and other runtime files that you created, so
+be careful.
+
+Else, if you installed Vim with the zip archives, the preferred way is to use
+the "uninstall" program. You can find it in the same directory as the
+"install" program, e.g., "c:\vim\vim82". This should also work from the usual
+"install/remove software" page.
+ However, this only removes the registry entries for Vim. You have to
+delete the files yourself. Simply select the directory "vim\vim82" and delete
+it recursively. There should be no files there that you changed, but you
+might want to check that first.
+ The "vim" directory probably contains your vimrc file and other runtime
+files that you created. You might want to keep that.
+
+==============================================================================
+
+Table of contents: |usr_toc.txt|
+
+Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: