compiling.txt Compiling                                  Jan 06, 2006
Author:  Charles E. Campbell, Jr.  <NdrOchip@ScampbellPfamily.AbizM>
          (remove NOSPAM from Campbell's email first)
Copyright: (c) 2005-2006 by Charles E. Campbell, Jr.    compiling-copyright
           The VIM LICENSE applies to compiling.vim (see copyright) except
           use "compiling.vim" instead of "Vim". No warranty, express or
           implied.  Use At-Your-Own-Risk.  Note that this copyright does
           not cover errsign.vim, although there's still no warranty, express
           or implied, with it, and it is also "use at your own risk".

1. Contents                              compiling compiling-contents

        1. Contents.................: compiling-contents
        2. Installing...............: compiling-install
        3. Tutorial.................: compiling-tutorial
        4. Manual...................: compiling-manual
        5. History..................: compiling-history

2. Installing                                 compiling-install

        (note: works best if you have the +signs feature in your copy of vim)

        a) First, note that this tarball contains the following files: >

           In particular, check your .vim/compiler directory _before_
           extracting files from the tarball.  Save those you wish to
           keep first.  Alternatively, unpack the tarball in a "sandbox"
           directory and only copy those files that you want to your
           .vim/compiler directory.

           If you're already using Ilya Skriblovsky's errsign.vim plugin,
           please note that this one will overwrite it.  This copy has
           been modified from Ilya Skriblovsky's version.

        b) <mkvim> is a Kornshell script.  Changing it to use bash should not
           be a problem.  However, it should be placed in some directory on
           your path.  The one I provided works with gcc; to use other
           compilers, you'll need to make some straightforward modifications.

           The mkvim script as provided uses two environment variables, and
           the commands in the compiler scripts use an additional one.  You'll
           need to make sensible versions thereof: >

                export ILIST="-I. -I.."
               export LLIST="-lmalloc -lm"
               export RM="${HOME}/.RM"

<          The ILIST is a list of include paths for header files.
           The LLIST is a list of libraries you like to have for linking.
           The RM environment variable holds a temporary directory.  I like to
           override the rm command with a function such as: >
               function rm
               /bin/mv -f $* ${HOME}/.RM
<          This gives me a way to quickly recover if I've removed some file;
           its not actually been removed, instead its been moved to ${RM}.
           My <.profile> (a startup script for Kornshell) has within it: >
                /bin/rm -r -f ~/.RM/* ~/.RM/.[a-zA-Z0-9]*
<          so "removed" (actually copied) files are really removed the next
           time I bring up a new shell.

           Generally the definitions for these environment variables should
           go into your initialization script (.profile, .bash_profile, etc).

           The mkvim script is used by the Chk command provided by the various
           compiler scripts.

        c) Change to the directory where you've decided to install the
           compilers tarball: >

               gunzip compilers.tar.gz
               tar -oxvf compilers.tar
        d) You'll need to specify a compiler in your <.vimrc>.  My <.vimrc>
           has something like: >

               if has("win32")
                compiler cygwin
               elseif $HOSTNAME == "hostname1"
                compiler gcc
               elseif $HOSTNAME == "hostname2"
                compiler irix6_c

<          where hostname1 and hostname2 are the names of machines I use.

        e) Your version of vim needs to have +signs.  To check on whether
           your vim has been compiled with +signs, type >

                :echo has("signs")

<          If your vim has +signs (which also appears when you type :version),
           answer should be 1.  Compiling vim configured with large or huge will
           give you the +signs feature: >

               configure --with-features=huge

3. Tutorial                                     compiling-tutorial

        Let's write a C program with an obvious error: >

               #include <stdio.h>
               int main()
               return 0;

<       Clearly "x" has not been defined; hence when the compiler sees it,
        it will complain.  Type >


<       I'll assume that you're using the gcc compiler, and that >

               compiler gcc

<       has already been placed in your <.vimrc> file.  You should see
        something like: >

                 #include <stdio.h>
                 int main()
                 return 0;
               hello.c|4 error| 'x' undeclared (first use in this function)
               hello.c|4 error| (Each undeclared identifier is reported only once
               hello.c|4 error| for each function it appears in.)

<       The upper window displays the source file with the error in Error
        highlighting (generally white lettering on a red background).  The
        cursor will be on the error, too.  In fact, generally it will even
        be on the column of the error.  The error message will show up on
        the bottom window.  To restore the display to just the usual source,
        type >


<       To clear only the error bar(s) and signs, leaving the error messages,
        type >


<       After making corrections, changing the source to: >

               #include <stdio.h>
               int main()
               int x;
               return 0;

<       and typing >


<       you'll find the error display completely cleared.

        When you're done checking your source code, you can then compile it
        to object (.o) or to executable formats.  Continuing with our example,
        type >


<       and you'll have a newly compiled program (hello).

4. Manual                                         compiling-manual

        :Chk    -- check your source code for errors, warnings, etc.
        :ChkOff -- clear error display
        :Ccd    -- compile to executable with -DDEBUG
        :Ccdo   -- compile to object form with -DDEBUG
        :CCdt   -- compile to executable with -DDEBUG_TEST and -DDEBUG
        :CCdto  -- compile to object form with -DDEBUG_TEST and -DDEBUG
        :Ccln   -- compile to executable (-O optimization)
        :Cco    -- compile to object form (-O optimization)
        :Cct    -- compile to executable form with -DDEBUG_TEST
        :Lex    -- run source through lex
        :Yacc   -- run source through yacc

        The <errsign.vim> plugin contained herein was written by Ilya
        Skriblovsky; I've modified it a bit, but its his plugin.  The
        original is available at:

5. History                                       compiling-history

        v1  Jan 06, 2006 : initial release