INTRO
I've being customizing my Vim installation and i wanted to share how i solved some common problems, my customizations were all about productivity and removing annoyances.
What are you going to get:
- The latest Vim compiled with python support
- Code completion for python AND django(full working no annoyances).
- Textmate like snippets to aid you when defining functions or classes and other python structures.
- Autoclosing some characters like ( with ) or [ with ] and so on.
- Being able to surround code with ' " ( [ or any html tag, quickly and delete surrounding code too.
- Python syntax highlighting.
- Python syntax error highlighting on the fly.
- Inside vim you'll be able to see the Docstrings for functions, methods, classes, really for newbies, optional for pros.
- Being able to comment code with a toggle hotkey, the quickest way.
- Auto indenting done right for python (the default autoindeting in Vim is not very good for python).
- A ver intuitive and quick interface to navigate through folders for files, lighting quick.
- Quickly opening your most recently used files.
- Some fixes for users coming from using GUI text editors.
- Running python scripts with a hotkey.
How is this post laid out
I'll include as many details as possible, because, while researching to solve my problems, i often ran into undocumented issues. I'll put this document in the order of events. I strongly recommend using ctrl+f in your browser to search for specific parts. I also added relevant links like this [1] check them out if you want additional information.
Some basic assumptions:
- GNU Linux - Ubuntu 10.10 Maverick
- This reference guide will probably work with newer ubuntu versions,
- I'm assuming you can do basic stuff on the command line.
- You really want the best Vim experience for python.
- And you know basic Vim usage.
The first thing i did was compile Vim from sources because the version included in ubuntu 10.10 is Vim 7.2 and i wanted the latest Vim 7.3 with full python support. You can see which version of vim you have with.vim --version
COMPILING VIM 7.3
First you have to get it from the repository using Mercurialhg clone https://vim.googlecode.com/hg/
If you don't have the hg command install it
sudo apt-get install mercurial
The hg clone will create a directory called vim then you need to go to the src folder inside that dir.
cd vim/src
And then you need to configure your installation for your own system, as you don't want to mix this compiled vim with the one you get using apt-get on ubuntu (i uninstalled that one) you can do it, but you don't have to unless you want your compiled version to open when you type vim on your terminal.
If you want to completly uninstall the built-in ubuntu vim do
sudo apt-get purge vim
And then you can delete the folder vim uses to customize for your user
rm -r ~/.vim
Another file important to remember is .vimrc this file is located in your home folder and even the compiled Vim will use it so you can keep previous modifications to this file.
Now we want to configure the installation before compiling this is the line i issued
./configure --prefix=${HOME}/apps/vim73 --with-features=huge --enable-gui=gnome2 --enable-pythoninterp --enable-rubyinterp --enable-multibyte --with-python-config-dir=/usr/lib/python2.6/config
Now take this line and paste it in your text editor(vim, hopefully) to edit it to your needs, ill guide you in each part of that line. The first part:
./configure
Configure is the standard script in many linux sources used to configure them before compiling them you can ask it all the commands available using:
./configure --help
The next option i added was
--prefix=${HOME}/apps/vim73
The part after = is the installation path, thats where you are going to keep all the vim files, including plugins and customizations (with the exception of the .vimrc that still lives in the root of your home folder)
I chose to use my home dir in a directory where i keep all my custom apps.
Continuing with the line
--with-features=huge
With this you tell vim, that you want the full featured vim default installation, i noticed that this gives you lots of plugins for standard functionality like editing zip files directly or highlighting for PHP and C. This line is important because when you are getting help online(in forums, blogs, the Vim manual) many things are assumed of your Vim installation, so you better keep it, you can always delete the added plugins.
This next line is only needed if you want gVim or the stand alone graphical interface vim, i really only use the command line vim but i could needed the GUI someday.
--enable-gui=gnome2
I must say that you won't get a menu entry for gVim in your ubuntu menu, but you will get the binary and you can add the entry your self.
This next line is for python, add it:
--enable-pythoninterp
You need ruby support for some plug-ins, and if of course if you want to edit ruby files sometime in the future.
--enable-rubyinterp
--enable-multibyte
You have to add that line if you are going to work with characters outside the ASCII world, basically if you are going to work with text thats not english, add it.
The last option has to be customized for the version of python you want vim to use to run some plugins. And don't worry you'll be able to run your own code with whatever version of python you want,
--with-python-config-dir=/usr/lib/python2.6/config
Just change the 2.6 to the version you have.
This config is actually config.c a filed added in all python installations from the ubuntu repositories, i had to install Python 2.5 from external repos and i didn't get this file but the only problem i've seeing is with google appengine applications, as google only supports Python 2.5 and Vim will show warnings when running some legacy code, like importing the sets module, that got deprecated in Python 2.6.
I've seen people online compiling vim with python 3.0 [1] but they ran into some problems, i can't help in that regard.
Copy your customized configure line and paste it on the terminal thats browsing the src folder, and run it then and wait for it to finish, if you have errors check for spelling mistakes using
./configure --help as reference.
Now that we have our vim sources configured lets put the machine to actually compile issuing a simple:
make
It will take a while depending on your machine, you can go take a coup of coffee and come back when its done to issue this next command:
make install
Once make install is done you'll have a working vim installation on the folder you choose using the --prefix option.
cd /home/grillermo/apps/vim73
Inside that dir you'll have 2 folders share and bin
The bin dir is where the vim binary lives and you can run it inside there using a simple:
./vim
Or for the graphical gnome vim
./gvim
Inside share/vim/vim73 you'll put your plugins and add-ons, this folder is the equivalent of the ~/.vim directory that the repositories Vim uses for plugins and add-ons.
If you decided to keep the default Vim and your compiled Vim you can check that they are two different versions easily with the --version flag:
vim --version
./vim --version
THE DEVELOPMENT ENVIRONMENT
I recommend reading Tools of the Modern Python Hacker: for the installation and usage of virtualenv, fabric and pip, i don't use fabric but i know i will when i start deploying.
The main issue we will solve here is how to fix the autocompletion for django and python, the problem is that we need to add some enviromental variables for each file, lets create that file:
sudo ./vim /usr/local/bin/vi
We created a file called vi, this is how you can keep 2 versions of Vim, one is called with Vim and your compiled one with Vi.
Now, read this code and paste it on our newly created file.
#!/bin/bash
export PROJECT=`python -c 'import os; print os.path.basename(os.getcwd())'`
export PYTHONPATH="/home/grillermo/c/bandtastic/python/"
export DJANGO_SETTINGS_MODULE=$PROJECT.settings/home/grillermo/apps/vim73/bin/vim $@
You have to customize a couple of things, first thing to know is that i keep all my django projects in /home/grillermo/c/bandtastic/python/ . Right now i'm working on /home/grillermo/c/bandtastic/python/dev , my project is called dev i cd to that path and then i open files like this
vi manage.py
And if i have a django app called polls i would open its model like this
vi polls/model.py
Why you need to know this? because this is the workflow you want, you want to keep all your django projects in one folder in my case is
/home/grillermo/c/bandtastic/python/ and inside that folder create a folder for each project and do not cd into any subdirectories, because otherwise the script we created won't work.
Ok if you already customized the vi file, now save it and go back to the terminal you'll need to give it execution privileges.
sudo chmod +xX vi
And thats it, if you wan't to test if this worked go to the folder you keep all your django projects
type
vi
And then type
:python from django import db
If you don't see any errors, your autocompletion will work now.
THE PLUGINS
In the interest of doing the plugin part of this post as simple as posible and if you want all the features i talked about at the benning of this posts i made a small zip with all the plugins so you can just extract the zip on your vim73/share/vim/vim73 folder,
The zip [MU]
Note: you'll probably want the latest version of the plugins, this zip file has the newest version up to the time of this post September 11, 2011 , links are provided to each plugin's home to get the latest version.
You can the plugins installation using nautilus or your favorite file browser.
Lets review them one by one, so you'll know exactly what you are getting.
PATHOGEN
This plugin is basic to avoid littering your plugins directory, it allows you to put the plugins in their own folders so if you don't like one, instead of hunting down the many files some plugins have scattered in different folders you just delete one folder. This plugin works by expecting you to make a folder inside vim73/share/vim/vim73/bundle for each plugin where you can extract the plugin's zip file content. Very handy for trying out different plugins.
To install it put the pathogen.vim in your vim73/share/vim/vim73/autoload/ folder.
In the .vimrc customization section of this post you'll find the line needed to actually enable it.
Create the folder bundle in your vim73/share/vim/vim73/ folder so we can put the rest of the plugins there.
Update:
Solve the problem with the help tags rebuilding functionality of pathogen.
NEOCOMPLCACHE
This is the all mighty autocompletion plugin, it works along side the omnicompletion feature include since vim 7 to provide autcompletion with the key on your keyboard, when you type a word and then hit tab it will autocomplete with the best choice, while editing a .py file if you type:
str.
You'll get a popup window with the available methods for the str object. The cool thing about this is that it'll work with django objects so for example when creating a model you'll see in a nice pop up with all the posible model fields and autocomplete them with .
To install it create create a folder(the name doesnt matter) inside bundle and extract the contents of neocomplcache-6.1.zip file on that folder.
And you'll get the line needed to enable it on the .vimrc section of this post.
You can study the different options for this plugin here, but only adding the line i provide its enough.
PYFLAKES
This is the sintax error highlighting plugin for python, it marks a line with red if the line is not valid python or if an import is not being used.
To install it create a folder inside bundle and extract the contents of pyflakes-vim.zip there.
No need to add lines to .vimrc to enable it.
AUTOCLOSE
This plugin as its name suggests it will auto close your parens ( or your brakets [ and put the cursor inside them, it will work with quotes ' and double quotes " too, pretty basic for every coder.
To install it copy autoclose.vim to vim73/share/vim/vim73/plugin , for this plugin we don't use the bundle folder because its only one file to install or remove.
COMMAND-T
This is a very intuitive file opener, it will autocomplete paths and show you the file thats the most likely to what you are writting, go to the site and see its amazing features.
The installation for this one is different because by default the author provides a vimball and vimballs break the pathogen usage, so we have to install it differently using git, if you don't have git a simple
sudo apt-get install git
Is enough. Now cd to to your bundle dir and do
git clone git://git.wincent.com/command-t.git command-t
Since this is a plugin with ruby, we need rake to compile it,
sudo apt-get install rake
Then cd to the command-t folder and do
rake make
While the Vimball installation automatically generates the help tags, under Pathogen it is necessary to do so explicitly from inside Vim:
:call pathogen#helptags()
*This installation instructions comes directly from the docs of the plugin.
To see this plugin in all its awesomness go to the authors website.
NERDTREE
This plugin is a file and directory browser, you'll be editing multiple files and this plugin will be useful if you are not sure whats the name of the file or in which dir is it. It does have a learning curve and you'll need to learn a few hotkeys. But it is way faster than going to your file browser looking for the file and then going back to vim to write all the path to the file to open it.
To install it, create folder in bundle and extract the contents of the zip.
In the plugin's wiki you'll find all you need to use it.
SURROUND
Visit the plugins page right now.
You'll need this plugin in python if you usually get into deeply nested functions or to quickly convert a tuple with hardcoded items to a list or a double quoted string to single quote.
To install it make a folder for it inside the bundle dir and extract the surround.zip in it.
And then learn its commands, i found that if i say the commands in my mind i remember them, the plugins page's first example goes like this:
Press cs"' (that's c, s, double quote, single quote) inside
"Hello world!"
Now, while typing cs"' you can say in your mind: change surrounding double quote into quotes following the typing and you'll have no trouble remembering them.
TCOMMENT
Of all the plugins to comment code out there i found this the easiest to use, you just type ctrl _ thats ctrl shift - , on american keyboards and you comment the line in the cursor, and you use the same hotkey with a visual block selected. If you found another thats simpler than that let me know.
To install make a folder in bundle and extract tcomment_vim.zip in it.
SIMPLYFOLD
There are many folding plugins, but this one is the closest to get it right, the author has fixed a couple of bugs i reported really quickly, he seems determined to make it the best, and it shows. Save your self all the trouble and use it.
THE VIMRC
Now lets begin customizing vim, the best way to do it is first showing you my .vimrc exactly as it is. Lets remember that file is the per-user config file vim uses for any user customizations, every Vim user has this file heavly edited. It lives in ~/.vimrc
.vimrc
I'm linking to the file because blogger tends to do ugly stuff to ' " and other characters. Open it in a text editor, see the lines you are interested and add them to your own .vimrc , in the PLUGINS area you'll see the lines needed to enable neocomplcache and pathogen plugins.
TROUBLESHOTTING
One particular problem you'll face is the that the autocomplete function won't work if you Vim doesn't see the DJANGO_SETTINGS_MODULE environmental variable, this used to require hacks and nasty work arounds, but today i found a
nice plugin for Vim that handles all those ugly details.
FINAL NOTES
Autocomplete will work thanks to neocomplcache, but using it you won't get the docstrings of each method and class, i leave it like this because the docstrings are displayed in a new window inside Vim and that can be annoying, you can access only when you need them using ctrl+space.
Vim is all about productivity i suggest you keep open the Vim documentation all the time while you are learning.
#TODO:
I'm still working on improving my Vim installation but i set out a personal policy to only spend time customizing Vim when i actually need it, because you don't want to over do customizations and never get actual work done, thats why i HAVE NOT worked on adding these features:
Code folding.- Quick navigation through classes and defs.
- Django template system highlighting and autocompletion.
- Integrating django commands on my work flow, like deploying and testing.
- Help in running tests on my code.
- Help when refactoring code.
I'll update this post as i add them.
Please comment and ask freely i want to know what issues you have so i can update the post.
References:
