doc/SingleCompile.txt

*SingleCompile.txt*

File: SingleCompile.txt
Version: 2.10.6
Original Author and Current Maintainer: Hong Xu <dev@hong.me>
Last Change: 15 May 2012
Homepage: http://www.vim.org/scripts/script.php?script_id=3115
GitHub repo: https://github.com/xuhdev/SingleCompile
Description: Make it more convenient to compile or run a single source file.
License:
    Copyright (C) 2010-2012 Hong Xu

    This file is part of SingleCompile.

    SingleCompile is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    SingleCompile is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with SingleCompile.  If not, see <http://www.gnu.org/licenses/>.

CONTENTS~
                                            *SingleCompile-contents*
----------------------------------------------------------------------------
1.  Overview                                 |SingleCompile-overview|
2.  Installation                             |SingleCompile-installation|
3.  Commands                                 |SingleCompile-commands|
4.  Settings                                 |SingleCompile-settings|
5.  Key-mappings                             |SingleCompile-key-mapping|
6.  Compiler template                        |SingleCompile-compiler-template|
7.  Supporting plugins                       |SingleCompile-supporting-plugins|
8.  Advanced                                 |SingleCompile-advanced|
9.  Credits                                  |SingleCompile-credits|
10. Todo                                     |SingleCompile-todo|


OVERVIEW~
                                            *SingleCompile-overview*
----------------------------------------------------------------------------
This plugin is aimed at making it more convenient to compile or run a single
source file without leaving vim.

A short introduction is available here:
http://hong-xu.github.com/blog/2012/03/07/use-singlecompile-to-compile-and-run-a-single-source-file-easily-in-vim/ 

Consider this situation: you have just written a small c source file for a
small test, but you have to write a Makefile to compile it or exit vim to
compile it or compile it using "!gcc" without quickfix feature because vim's
make command only use the "make" command? This plugin will help you out.

Add these key-mappings to your vimrc:
>
 nmap <F9> :SCCompile<cr>
 nmap <F10> :SCCompileRun<cr>
<
Note that the two lines here should not have any trailing space. If your file
type is supported, then press F9 to compile your source file, and press F10 to
compile and run your source file. If there is a compilation error, and the
|quickfix| feature is enabled, then you could use |:cope| command to see the
error list. You may also use ":SCChooseCompiler" command to choose a compiler
if you have more than one kind of compiler available on you system.
":SCViewResult" will show you the last run result.


Features:
1. Compile or run the source file quickly using |quickfix| feature and
   |compiler| feature of vim;
2. Compilers and interpreters auto detecting;
3. Fast switch between several installed compilers or interpreters;
4. Multi-language support;
5. Custom your own compiler/interpreter template;
6. View the result of last run command at any time(requires "tee" command);
7. Run the compiled program asynchronously and view the result at any time
   (see |:SCCompileRunAsync|).


Here is a list of built-in supported compilers or interpreter(For some
compilers/interpreters, you need to set the environment varibles correctly to
make them available for SingleCompile):

Ada:
    gnat (GNAT)

bash:
    bash (Bourne-Again Shell)

C:
    bcc (Borland C++ Builder), Windows only
    cc (UNIX C Compiler), UNIX only
    ch (SoftIntegration Ch)
    clang (the Clang C and Objective-C compiler)
    gcc (GNU C Compiler)
    icc (Intel C++ Compiler)
    lcc (Little C Compiler)
    msvc (Microsoft Visual C++ (In PATH)), Windows only
    msvc80 (Microsoft Visual C++ 2005), Windows only
    msvc90 (Microsoft Visual C++ 2008), Windows only
    msvc100 (Microsoft Visual C++ 2010), Windows only
    open-watcom (Open Watcom C/C++32 Compiler)
    open64 (Open64 C Compiler), UNIX only
    pcc (Portable C Compiler)
    sol-studio (Sun C Compiler(Sun Solaris Studio)), UNIX only
    tcc (Tiny C Compiler)
    tcc-run (Tiny C Compiler with "-run" Flag)

C++:
    bcc (Borland C++ Builder), Windows Only
    ch (SoftIntegration Ch)
    clang (the Clang C and Objective-C compiler)
    g++ (GNU C++ Compiler)
    icc (Intel C++ Compiler)
    msvc (Microsoft Visual C++ (In PATH)), Windows only
    msvc80 (Microsoft Visual C++ 2005), Windows only
    msvc90 (Microsoft Visual C++ 2008), Windows only
    msvc100 (Microsoft Visual C++ 2010), Windows only
    open-watcom (Open Watcom C/C++32 Compiler)
    open64 (Open64 C++ Compiler), UNIX only
    sol-studio (Sun C++ Compiler(Sun Solaris Studio)), UNIX only

C#:
    msvcs(Microsoft Visual C#), Windows Only
    mono (Mono C# compiler)

cmake:
    cmake (cmake)

csh:
    csh (C Shell)
    tcsh (TENEX C Shell)

D:
    dmd (DMD Compiler)

dos batch:
    dosbatch (DOS Batch)

erlang:
    escript (Erlang Scripting Support)

Fortran:
    ftn95 (Silverfrost FTN95), Windows only
    g77 (GNU Fortran 77 Compiler)
    g95 (G95)
    gfortran (GNU Fortran Compiler)
    ifort (Intel Fortran Compiler)
    open-watcom (Open Watcom Fortran 77/32 Compiler)
    open64-f90 (Open64 Fortran 90 Compiler), UNIX only
    open64-f95 (Open64 Fortran 95 Compiler), UNIX only
    sol-studio-f77 (Sun Fortran 77 Compiler(Sun Solaris Studio)), UNIX only
    sol-studio-f90 (Sun Fortran 90 Compiler(Sun Solaris Studio)), UNIX only
    sol-studio-f95 (Sun Fortran 95 Compiler(Sun Solaris Studio)), UNIX only

Haskell:
    ghc (Glasgow Haskell Compiler)
    runhaskell (runhaskell)

html:
    arora (Arora)
    chrome (Google Chrome)
    epiphany (Epiphany)
    firefox (Mozilla Firefox)
    ie (Microsoft Internet Explorer)
    konqueror (Konqueror)
    opera (Opera)

IDL(Interactive Data Language):
    idl (ITT Visual Information Solutions Interactive Data Language)
    gdl (GNU Data Language incremental compiler)

Java:
    gcj (GNU Java Compiler)
    sunjdk (Sun Java Development Kit)

JavaScript:
    gjs (Javascript Bindings for GNOME)
    js (SpiderMonkey, a JavaScript engine written in C)
    node.js (node.js)
    rhino (Rhino, a JavaScript engine written in Java)

ksh:
    ksh (Korn Shell)

LaTeX:
    latex (LaTeX)
    pdflatex (pdfLaTeX)

LISP:
    clisp (GNU CLISP)
    ecl (Embeddable Common-Lisp)
    gcl (GNU Common Lisp)

lua:
    lua (Lua Interpreter)

Makefile:
    gmake (GNU Make)
    nmake (Microsoft Program Maintenance Utility)
    mingw32-make (MinGW32 Make)

Markdown:
    markdown (text-to-HTML conversion tool)
    rdiscount (Discount Markdown Processor for Ruby)

Object-C:
    clang (the Clang C and Objective-C compiler)
    gcc (GNU Object-C Compiler)

Pascal:
    fpc (Free Pascal Compiler)
    gpc (GNU Pascal Compiler)

perl:
    perl (Perl Interpreter)

PHP:
    php (PHP Command Line Interface 'CLI')

python:
    ironpython (IronPython)
    jython (Jython)
    pypy (PyPy)
    python (Python Interpreter)
    python3 (Python 3 Interpreter)

R:
    R (R)

reStructuredText:
    rst2html (reST to HTML)

ruby:
    ruby (Ruby Interpreter)

sh:
    ash (Almquist Shell)
    bash (Bourne-Again Shell)
    dash (Debian Almquist Shell)
    ksh (Korn Shell)
    sh (Bourne Shell)
    zsh (Z Shell)

tcl:
    tclsh (Simple shell containing Tcl interpreter)

tcsh:
    tcsh (TENEX C Shell)

vb script:
    vb (VB Script Interpreter)

xhtml:
    arora (Arora)
    chrome (Google Chrome)
    chromium (Chromium)
    epiphany (Epiphany)
    firefox (Mozilla Firefox)
    ie (Microsoft Internet Explorer)
    konqueror (Konqueror)
    opera (Opera)

zsh:
    zsh (Z Shell)

You can add your compiler or interpreter support if the compiler or
interpreter you want is not in the list. See details in the help file.

There are some supporting code in this plugin for Marc Weber's
vim-addon-actions:
     http://github.com/MarcWeber/vim-addon-actions

If you find any bug, please report it to xuhdev@gmail.com or submit it on
the issue tracker:
https://bitbucket.org/xuhdev/singlecompile/issues

If you've written some templates for some compilers or interpreters which are
not included as built-in template, and you think they are useful for other
people, you could send me an email to inform me, and I'll put them in the
built-in templates.


Git repository on github.com: https://github.com/xuhdev/SingleCompile
Mercurial repository on bitbucket.org: https://bitbucket.org/xuhdev/singlecompile

Follow xuhdev on twitter if you are interested in my development:
http://twitter.com/xuhdev


INSTALLATION~
                                            *SingleCompile-installation*
----------------------------------------------------------------------------
Download the SingleCompile.zip file and extract it to your vim runtime
directory(~/.vim on linux and $VIM_INSTALLATION_FOLDER\vimfiles on windows),
you'd better then use ":helptags" command to generate the help tag(for example
use ":helptags ~/.vim/doc" on UNIX/Linux).


COMMANDS~
                                            *SingleCompile-commands*
----------------------------------------------------------------------------

                                            *:SCCompile*
Command:
    :SCCompile
If you are editing a source file of a compiling language such as C, Java, this
command will compile the file which you are editing now. If you are editing a
source file of a interpreted language such as python language, this command
will run the file which you are editing. See |SingleCompile-compiler-template|
about the compilation command.

You can add some arguments after the command. For example, you want to compile
your c source file with "-g -o %<" flag instead of the "-o %<" flag defined in
the language template(see |SingleCompile-compiler-template|) for just this
time, just use the following command:
>
 :SCCompile -g -o %<
<
"%<" means the current file name without extension.
Also see |:SCCompileAF|.

                                            *:SingleCompile*
Command:
    :SingleCompile
Same as |:SCCompile|, only for backward compatibility use. Not recommended to
use any more.

                                            *:SCCompileAF*
Command:
    :SCCompileAF
This command is also used for compiling your source file, but it allows you to
append some additional compilation or interpretion flags other than the flags
already defined in the compiler and interpreter template. The "AF" is short
for "Addtional Flags". For example, GCC compiler for C has already been
defined some flags: "-o "%<"". But sometimes you also want to use "-O2" flag
to optimize your code, then you can use the following commands to compile your
file:
>
 :SCCompileAF -O2
<
:SCCompile can also be used with some arguments, but there are some
differences. :SCCompileAF use your arguments as "additional" compilation
flags, which means the flags defined in the original templates are also valid,
while :SCCompile use you arguments as compilation flags only, which means the
flags defined in the original templates are not used. For example, the
templates of GCC defined "flags" as '-o "%<"', "%<" stands for the output file
name. ":SCCompile -O2" will use "gcc -O2 some_file.c" to compile your source
file, while ":SCCompileAF -O2" will use "gcc -o some_file -O2 some_file.c" to
compile your source file.

                                            *:SCCompileRun*
Command:
    :SCCompileRun
If you are editing a source file of a compiling language such as C, Java, this
command will compile the file which you are editing now and run the
executable; if you are editing a source file of a interpreted language such as
python, ruby, this command will run the source file you are editing. That
means, there is nothing different between |:SCCompile| and |:SCCompileRun| for an
interpreted language source file.

You can also add some arguments after SCCompileRun command, the meaning of
arguments is the same as SingleCompile command above. Here is an example:
>
 :SCCompileRun -g -o %<
<

When the program you've just compiled (or the script you've just written)
runs, vim will hang up to wait for the program to terminate. If you do not
want vim to hang up when running the program, use |:SCCompileRunAsync|
instead. See |:SCCompileRunAsync| for further information.

                                            *:SingleCompileRun*
Command:
    :SingleCompileRun
Same as |:SCCompileRun|, only for backward compatibility use. Not recommended
to use any more.

                                            *:SCCompileRunAF*
Command:
    :SCCompileRunAF
Same as |:SCCompileAF|, but also run the binary file after compilation. For
example, the following command is going to compile your source file with an
additional "-O2" flag and run the output binary file:
>
 :SCCompileRunAF -O2
<

                                            *:SCCompileRunAsync*
Command:
    :SCCompileRunAsync
Same as |:SCCompileRun|, but compile the source and run asynchronously. That
is to say, after the program starts to run, you are still able to edit the
source file, because vim does not hang up waiting for the program to
terminate. The result of the run could be viewed by |:SCViewResultAsync|
command. This command might not be available on your vim, see
|SingleCompile-asyncrunmode| for more information. This command is useful when
the program takes a long time to run or you are developing a GUI program. Also
see |:SCViewResultAsync|, |:SCTerminateAsync| and |:SCIsRunningAsync|.

                                            *:SCCompileRunAsyncAF*
Command:
    :SCCompileRunAsyncAF
Same as |:SCCompileRunAF|, but compile the source and run asynchronously. The
result of the run could be viewed by |:SCViewResultAsync| command. This
command is disabled by default, to enable it, see
|SingleCompile-asyncrunmode|. Also see |:SCCompileRunAsync|.

                                            *:SCChooseCompiler*
Command:
    :SCChooseCompiler
Choose a compiler to use. This command will display a list of compilers for
you to choose one. If you want to set a default compiler in your vimrc, please
use the function SingleCompile#ChooseCompiler. See
|SingleCompile-use-built-in-template|.

                                            *:SCChooseInterpreter*
Command:
    :SCChooseInterpreter
Same as |:SCChooseCompiler|.

                                            *:SCIsRunningAsync*
Command:
    :SCIsRunningAsync
Check whether the asynchronously run process is still running. Also see
|:SCCompileRunAsync|.

                                            *:SCTerminateAsync*
Command:
    :SCTerminateAsync
Terminate the process which is running asynchronously if exists. Also see
|:SCCompileRunAsync|.

                                            *:SCViewResult*
Command:
    :SCViewResult
View the result of the last run command. Only valid when "tee" command is
available.  "tee" is usually available on a UNIX system. If you are under
Windows, install cygwin or visit the following link to download a "tee"
command for Windows:
http://gnuwin32.sourceforge.net/packages/coreutils.htm

                                            *:SCViewResultAsync*
Command:
    :SCViewResultAsync
Same as |:SCViewResult|, but the result displayed is the result of the process
run by |:SCCompileRunAsync| or |:SCCompileRunAsyncAF|.


SETTINGS~
                                            *SingleCompile-settings*
----------------------------------------------------------------------------

                                            *SingleCompile-alwayscompile*
If g:SingleCompile_alwayscompile is set to 0, when using |:SCCompileRun|
command, SingleCompile may run the output of the compilation directly if the
modification time of the source file is earlier than the output file. If you
want to enable this feature, add the following line to your vimrc:
>
 let g:SingleCompile_alwayscompile = 0
<
The default value of g:SingleCompile_alwayscompile is 1.

                                            *SingleCompile-asyncrunmode*
This option specifies the asynchronous mode for |:SCCompileRunAsync| and
|:SCCompileRunAsyncAF|. The default value is "auto", which means SingleCompile
will automatically detect whether you are able to enable async run mode and
select one mode for you. Use the following line, replace modename with the
mode you want to change mode:
>
 let g:SingleCompile_asyncrunmode = 'modename'
<

Here is a list of available mode:

auto        This is the default value. SingleCompile automatically selects one
            mode for you.
>
 let g:SingleCompile_asyncrunmode = 'auto'
<

none        Disable asynchronous mode, which means |:SCCompileRunAsync| and
            |:SCCompileRunAsyncAF| and related commands are disabled.
>
 let g:SingleCompile_asyncrunmode = 'none'
<

python      Use python interface when running asynchronously. Required vim
            compiled with python interface 2.6+. See |+python|.
>
 let g:SingleCompile_asyncrunmode = 'python'
<


                                            *SingleCompile-autowrite*
If you don't want to save your file automatically when you use "SingleCompile"
command or "SingleCompileRun" command, add the following line to your vimrc:
>
 let g:SingleCompile_autowrite = 0
<
NOTE: If you let g:SingleCompile_usequickfix=1, this option will take no
effect, the running result will depend on the vim's option 'autowrite'. See
'autowrite' for more information.

                                            *SingleCompile-menumode*
If you don't want the menus of SingleCompile to show, copy the following line
to your vimrc:
>
 let g:SingleCompile_menumode = 0
<
If you want the menus of SingleCompile to show as a sub menu of Plugin, copy
the following line to your vimrc:
>
 let g:SingleCompile_menumode = 1
<
If you want the menus of SingleCompile to show in the menu bar, copy the
following line to your vimrc:
>
 let g:SingleCompile_menumode = 2
<
The default value is 1.

                                            *SingleCompile-resultheight*
g:SingleCompile_resultheight is the height of the result displaying window
triggered by |:SCViewResult| command. To set the value, add the following line
to your vimrc file:
>
 let g:SingleCompile_resultheight = a_number
<
Replace a_number to any number you want, such as "10", "4". The default value
of g:SingleCompile_resultheight is 5.

                                            *SingleCompile-showquickfixiferror*
If |quickfix| is enabled and used, and you want the quickfix window to show
automatically if there is a compilation error, then add the following line to
your vimrc file:
>
 let g:SingleCompile_showquickfixiferror = 1
<
The default value of g:SingleCompile_showquickfixiferror is 0. Note that this
option will be ignored if you are using interpreting languages on Windows,
such as python, ruby.

                                            *SingleCompile-showresultafterrun*
If "tee" command is available on your system, copy the following line to your
vimrc file will make vim show the result of the run automatically after you
run the program:
>
 let g:SingleCompile_showresultafterrun = 1
<
This option is only valid for synchronous run. That is to say, asynchronous
run is not affected by this option. The default value of
g:SingleCompile_showresultafterrun is 0. Also see |:SCViewResult|.

                                            *SingleCompile-usedialog*
If you want SingleCompile to show message in a dialog, add the
following line to your vimrc:
>
 let g:SingleCompile_usedialog = 1
<
This setting will take no effect if your vim is not compiled with
'+dialog_con' and '+dialog_gui'.

                                            *SingleCompile-usequickfix*
If you don't want SingleCompile to use quickfix feature, add the following
line to your vimrc:
>
 let g:SingleCompile_usequickfix = 0
<


KEY-MAPPING~
                                            *SingleCompile-key-mapping*
----------------------------------------------------------------------------
I recommend you to copy the following two lines about key mapping to your
vimrc:
>
 nmap <F9> :SingleCompile<cr>
 nmap <F10> :SingleCompileRun<cr>
<
Then you can press F9 to compile, and F10 to compile and run.


COMPILER-TEMPLATE~
                                            *SingleCompile-compiler-template*
----------------------------------------------------------------------------
                                          *SingleCompile-use-built-in-template*
                                          *SingleCompile#ChooseCompiler*
To use a built-in compiler, add the following line to your vimrc file:
>
 call SingleCompile#ChooseCompiler('filetype', 'compiler')
<
"filetype" is the type of file which your compiler is for, such as "c",
"python", and "compiler" is the short name of the compiler. "filetype" is a
terminology of vim. See |filetype| if you don't know what is "filetype". For
example:
>
 call SingleCompile#ChooseCompiler('c', 'icc')
 call SingleCompile#ChooseCompiler('fortran', 'gfortran')
<
This will choose icc (short for Intel C++ Compiler) as your current C compiler
and choose gfortran (GNU Fortran Compiler) as your current Fortran compiler.
For the list of built-in supported compilers, see
|SingleCompile-built-in-compilers|.

If you don't choose a compiler by yourself, SingleCompile will automatically
choose one for you according to the compiler's priority value (See
|SingleCompile-priority|).

You can also extend the compiler template if the compiler you want is not in
the built-in supporting list. SingleCompile#ChooseCompiler could also be used
to choose a user defined compiler. Check |SingleCompile-add-your-compiler| for
more information.

                                          *SingleCompile-add-your-compiler*
                                          *SingleCompile#SetCompilerTemplate*
To add a new compiler support by yourself, there are two ways:
1. (Recommended) Add the following lines to your vimrc file:
>
 call SingleCompile#SetCompilerTemplate('filetype', 'compiler', 'compiler_name', 'command', 'flag', 'run_command')
 call SingleCompile#SetOutfile('filetype', 'compiler', 'out_file')
 call SingleCompile#ChooseCompiler('filetype', 'compiler')
<
Now Let's see the first line. "filetype" is the source file type, such as "c",
"cpp", "python", etc. It is a terminology of vim. See |filetype| if you don't
know what is "filetype". For compiling languages such as C, Java, Fortran,
"compiler" is the short name for the compiler, such as "gcc", "icc"; "command"
is the command of compiling, such as "gcc", "g++"; "flag" is the flags of
compiling, such as "-O2"; "run_command" is the command of running, such as
"./a.out". For interpreted languages such as Python, Ruby, "command" is the
command of interpreting, such as "python"; "flag" is the flags of
interpreting; and "run_command" MUST be set to be empty.

For the second line, "filetype" and  "compiler" has the same meanings with the
first line. "out_file" is the output file of the compilation, such as
"./a.out", "./a.exe", etc. This line could be omitted if you don't want
SingleCompile to check whether compilation is needed. See
|SingleCompile-alwayscompile| for more information.

The first two lines are to set the template of your compiler, while the third
line is to tell SingleCompile to use your compiler. If the second line is
omitted, SingleCompile will detect the compilers available on your system
automatically, and use the first detected one.

Here are some examples modified from built-in compiler templates:
>
 " set the most common used run command
 if has('win32') || has('win64') || has('os2')
     let l:common_run_command = '$(FILE_TITLE)$'
     let l:common_out_file = '$(FILE_TITLE)$.exe'
 else
     let l:common_run_command = './$(FILE_TITLE)$'
     let l:common_out_file = '$(FILE_TITLE)$'
 endif

 " c
 call SingleCompile#SetCompilerTemplate('c', 'gcc', 'GNU C Compiler',
             \'gcc', '-o $(FILE_TITLE)$', l:common_run_command)
 call SingleCompile#SetOutfile('c', 'gcc', l:common_out_file)
 call SingleCompile#SetCompilerTemplate('c', 'icc',
             \'Intel C++ Compiler', 'icc', '-o $(FILE_TITLE)$',
             \l:common_run_command)
 call SingleCompile#SetOutfile('c', 'icc', l:common_out_file)

 call SingleCompile#ChooseCompiler('c', 'gcc')

 " fortran
 call SingleCompile#SetCompilerTemplate('fortran', 'g77',
             \'GNU Fortran 77 Compiler', 'g77', '-o $(FILE_TITLE)$',
             \l:common_run_command)
 call SingleCompile#SetOutfile('fortran', 'g77', l:common_out_file)
 call SingleCompile#SetCompilerTemplate('fortran', 'ifort',
             \'Intel Fortran Compiler', 'ifort', '-o $(FILE_TITLE)$',
             \l:common_run_command)
 call SingleCompile#SetOutfile('fortran', 'ifort', l:common_out_file)

 call SingleCompile#ChooseCompiler('fortran', 'g77')

 " python
 call SingleCompile#SetCompilerTemplate('python', 'python', 'CPython',
             \'python', '', '')
 call SingleCompile#SetCompilerTemplate('python', 'jython', 'Jython',
             \'jython', '', '')

 call SingleCompile#ChooseCompiler('python', 'jython')
<

2. (Deprecated, only kept for backward compatibility use)
If you use this method to add a language template, many features of
SingleCompile will be unavailable. For example, ":SCChooseCompiler" command
will not be available. So I don't recommend you to use this method, and this
method is kept ONLY for backward compatibility.

Add the following lines to your vimrc file:
>
 call SingleCompile#SetTemplate('filetype', 'command', 'stringA')
 call SingleCompile#SetTemplate('filetype', 'flags', 'stringB')
 call SingleCompile#SetTemplate('filetype', 'run', 'stringC')
<
For compiling languages such as C, Java, stringA is the command of compiling,
stringB is the flags of compiling, stringC is the command of running; For
interpreted languages such as Python, Ruby, stringA is the command of
interpreting, stringB is the flags of interpreting, stringC MUST be set to
be empty.

Here are some examples:
>
 " java
 call SingleCompile#SetTemplate('java', 'command', 'javac')
 call SingleCompile#SetTemplate('java', 'flags', '')
 call SingleCompile#SetTemplate('java', 'run', 'java %<')

 " python
 call SingleCompile#SetTemplate('python', 'command', 'python')
 call SingleCompile#SetTemplate('python', 'flags', '')
 call SingleCompile#SetTemplate('python', 'run', '')

 " latex
 call SingleCompile#SetTemplate('tex', 'command', 'latex')
 call SingleCompile#SetTemplate('tex', 'flags', '')
 if has('unix')
     call SingleCompile#SetTemplate('tex', 'run', 'xdvi %<.dvi')
 elseif has('win32')
     call SingleCompile#SetTemplate('tex', 'run', 'dviout %<.dvi')
 endif
<
You can also use this method to modify the templates of a built-in supported
language. For example, you can change 'dviout' to 'yap' in the example above
to modify the built-in latex language template.

Advanced: If you don't want to override the template if there is an existing
one, but use the new template if there is no corresponding template existing,
for example, you want to set the "command" of java language to javac if no
command is set for java, but do nothing if the command of java is not set, use
the following:
>
 call SingleCompile#SetTemplate('java', 'command', 'javac', 1)
<
In this way, if the command of java is already set, this sentence will do
nothing. On the contrary, if the command of java is not set, it will set the
compilation command of java to "javac".

                                            *SingleCompile-built-in-compiler*
The following compilers have built-in support in this plugin (For some
compilers/interpreters, you need to set the environment varibles correctly to
make them available for SingleCompile):

Ada:
    gnat (GNAT)

bash:
    bash (Bourne-Again Shell)

C:
    bcc (Borland C++ Builder), Windows only
    cc (UNIX C Compiler), UNIX only
    ch (SoftIntegration Ch)
    clang (the Clang C and Objective-C compiler)
    gcc (GNU C Compiler)
    icc (Intel C++ Compiler)
    lcc (Little C Compiler)
    msvc (Microsoft Visual C++ (In PATH)), Windows only
    msvc80 (Microsoft Visual C++ 2005), Windows only
    msvc90 (Microsoft Visual C++ 2008), Windows only
    msvc100 (Microsoft Visual C++ 2010), Windows only
    open-watcom (Open Watcom C/C++32 Compiler)
    open64 (Open64 C Compiler), UNIX only
    pcc (Portable C Compiler)
    sol-studio (Sun C Compiler(Sun Solaris Studio)), UNIX only
    tcc (Tiny C Compiler)
    tcc-run (Tiny C Compiler with "-run" Flag)

C++:
    bcc (Borland C++ Builder), Windows Only
    ch (SoftIntegration Ch)
    clang (the Clang C and Objective-C compiler)
    g++ (GNU C++ Compiler)
    icc (Intel C++ Compiler)
    msvc (Microsoft Visual C++ (In PATH)), Windows only
    msvc80 (Microsoft Visual C++ 2005), Windows only
    msvc90 (Microsoft Visual C++ 2008), Windows only
    msvc100 (Microsoft Visual C++ 2010), Windows only
    open-watcom (Open Watcom C/C++32 Compiler)
    open64 (Open64 C++ Compiler), UNIX only
    sol-studio (Sun C++ Compiler(Sun Solaris Studio)), UNIX only

C#:
    msvcs(Microsoft Visual C#), Windows Only
    mono (Mono C# compiler)

cmake:
    cmake (cmake)

csh:
    csh (C Shell)
    tcsh (TENEX C Shell)

D:
    dmd (DMD Compiler)

dos batch:
    dosbatch (DOS Batch)

erlang:
    escript (Erlang Scripting Support)

Fortran:
    ftn95 (Silverfrost FTN95), Windows only
    g77 (GNU Fortran 77 Compiler)
    g95 (G95)
    gfortran (GNU Fortran Compiler)
    ifort (Intel Fortran Compiler)
    open-watcom (Open Watcom Fortran 77/32 Compiler)
    open64-f90 (Open64 Fortran 90 Compiler), UNIX only
    open64-f95 (Open64 Fortran 95 Compiler), UNIX only
    sol-studio-f77 (Sun Fortran 77 Compiler(Sun Solaris Studio)), UNIX only
    sol-studio-f90 (Sun Fortran 90 Compiler(Sun Solaris Studio)), UNIX only
    sol-studio-f95 (Sun Fortran 95 Compiler(Sun Solaris Studio)), UNIX only

Haskell:
    ghc (Glasgow Haskell Compiler)
    runhaskell (runhaskell)

html:
    arora (Arora)
    chrome (Google Chrome)
    chromium (Chromium)
    epiphany (Epiphany)
    firefox (Mozilla Firefox)
    ie (Microsoft Internet Explorer)
    konqueror (Konqueror)
    opera (Opera)

IDL(Interactive Data Language):
    idl (ITT Visual Information Solutions Interactive Data Language)
    gdl (GNU Data Language incremental compiler)

Java:
    gcj (GNU Java Compiler)
    sunjdk (Sun Java Development Kit)

JavaScript:
    gjs (Javascript Bindings for GNOME)
    js (SpiderMonkey, a JavaScript engine written in C)
    node.js (node.js)
    rhino (Rhino, a JavaScript engine written in Java)

ksh:
    ksh (Korn Shell)

LaTeX:
    latex (LaTeX)
    pdflatex (pdfLaTeX)

LISP:
    clisp (GNU CLISP)
    ecl (Embeddable Common-Lisp)
    gcl (GNU Common Lisp)

lua:
    lua (Lua Interpreter)

Makefile:
    gmake (GNU Make)
    nmake (Microsoft Program Maintenance Utility)
    mingw32-make (MinGW32 Make)

Markdown:
    markdown (text-to-HTML conversion tool)
    rdiscount (Discount Markdown Processor for Ruby)

Object-C:
    clang (the Clang C and Objective-C compiler)
    gcc (GNU Object-C Compiler)

Pascal:
    fpc (Free Pascal Compiler)
    gpc (GNU Pascal Compiler)

perl:
    perl (Perl Interpreter)

PHP:
    php (PHP Command Line Interface 'CLI')

python:
    ironpython (IronPython)
    jython (Jython)
    pypy (PyPy)
    python (Python Interpreter)
    python3 (Python 3 Interpreter)

R:
    R (R)

ruby:
    ruby (Ruby Interpreter)

sh:
    ash (Almquist Shell)
    bash (Bourne-Again Shell)
    dash (Debian Almquist Shell)
    ksh (Korn Shell)
    sh (Bourne Shell)
    zsh (Z Shell)

tcl:
    tclsh (Simple shell containing Tcl interpreter)

tcsh:
    tcsh (TENEX C Shell)

vb script:
    vb (VB Script Interpreter)

xhtml:
    arora (Arora)
    chrome (Google Chrome)
    epiphany (Epiphany)
    firefox (Mozilla Firefox)
    ie (Microsoft Internet Explorer)
    konqueror (Konqueror)
    opera (Opera)

zsh:
    zsh (Z Shell)


See |SingleCompile-add-your-compiler| to add your compiler support.


SUPPORTINGS~
                                            *SingleCompile-supporting-plugins*
----------------------------------------------------------------------------
There are some supporting code in this plugin for Marc Weber's
vim-addon-actions:
    http://github.com/MarcWeber/vim-addon-actions


ADVANCED~
                                            *SingleCompile-advanced*
----------------------------------------------------------------------------
This chapter is for advanced users.

                                    *SingleCompile-custom-compiler-detecting*
SingleCompile allows you to custom compiler detecting function by yourself.

In |SingleCompile-compiler-template|, the following function is introduced:
>
 call SingleCompile#SetCompilerTemplate('filetype', 'compiler',
             \'compiler_name', 'command', 'flag', 'run_command')
<

However, in fact, the function SingleCompile#SetCompilerTemplate could have a
seventh parameter. The seventh parameter is a |Funcref| which references to a
compiler detecting function. The compiler detecting function will be called in
the function SingleCompile#SetCompilerTemplate. The compiler detecting
function must accept one parameter, which would be passed in the "command"
parameter in SingleCompile#SetCompilerTemplate, and return a detected compiler
command if detected, which will be used as the compiling command by
SingleCompile, or returns 0 if the compiler is not detected. Thus, it is more
powerful to detect some compilers. If the seventh parameter is omitted, the
function will use a built-in default compiler detecting function instead. The
default function would check whether the "command" is in PATH, ~/bin,
/usr/local/bin, /usr/bin, /bin on UNIX and whether it is in PATH on other
OSes, and returns the full path of the command if it is not in PATH. If the
command is not detected, the default function would return 0.

Here is a short example excerpted from built-in template(OpenWatcom detecting
function):
>
 function! s:DetectWatcom(compiling_command)
     let l:watcom_command =
                 \SingleCompile#DetectCompilerGenerally(a:compiling_command)
     if l:watcom_command != 0
         return l:watcom_command
     endif

     if $WATCOM != ''
         return $WATCOM.'\binnt\'.a:compiling_command
     endif
 endfunction
<
SingleCompile#DetectCompilerGenerally is the default compiler detecting
function introduced in the above paragraph. This function first uses a general
way to detect the compiler. If the general way can not detect it, it check the
environment varible "$WATCOM" to get the compiler's installation directory and
get the full path of the compiling program.

                                            *SingleCompile-predo-postdo*
                                            *SingleCompile-predo*
                                            *SingleCompile-postdo*
                                            *SingleCompile#SetPredo*
                                            *SingleCompile#SetPostdo*
"Predo" and "Postdo" features allow you to initialize the compiler before
compiling and clean up after compiling in you own way.

"Predo" feature allows you to define a function, which would be called before
compiling by SingleCompile, all by yourself. In the same way, "Postdo" feature
allows you to define a function called by SingleCompile after compiling. Your
"Predo" or "Postdo" function should accept one parameter, which would be
passed in a dictionary containing compiling information, and return a new
compiling information modified in the function by you. SingleCompile will use
the new compiling information in its following work. The dictionary passed in
is like this: >
 {"command": "the-compiling-command", "args": "the-compiling-argument"}
>
Then modify the dictionary to meet your need and return the modified
dictionary. If you don't want to modify the dictionary, please return the
parameter passed in directly.

The two functions below provide a way to set the "Predo" and "Postdo"
functions:
>
 call SingleCompile#SetPredo('filetype', 'compiler',
             \function('your_predo_function'))
 call SingleCompile#SetPostdo('filetype', 'compiler',
             \function('your_postdo_function'))
<

Example: OpenWatcom's "Predo" and "Postdo" functions:
>
 " pre-do
 function! s:PredoWatcom(compiling_info)
     let s:old_path = $PATH
     let $PATH = $WATCOM.s:GetPathSeperator().'binnt'.s:GetEnvSeperator().
                 \$WATCOM.s:GetPathSeperator().'binw'.s:GetEnvSeperator().
                 \$PATH
     return a:compiling_info
 endfunction

 " post-do
 function! s:PostdoWatcom(compiling_info) " watcom pre-do {{{2
     let $PATH = s:old_path
     return a:compiling_info
 endfunction

 call SingleCompile#SetPredo('c', 'open-watcom', function('s:PredoWatcom'))
 call SingleCompile#SetPostdo('c', 'open-watcom', function('s:PostdoWatcom'))
<
As you see, the OpenWatcom "Predo" function first saves the current PATH
environment varible, then modifies $PATH to meet the OpenWatcom compiler needs.
It returns the original compiling info because it does not need to modify it.
The OpenWatcom "Postdo" function restores the original $PATH. After defining
the two functions, the example calls "SetPredo" and "SetPostdo" function to
set the functions as the "Predo" function and "Postdo" function for
corresponding language and compiler.


To make it less confusing, I better explain the calling order here. The
calling order is: first the compiler detecting function, then "Predo"
function, then compile, and the last is the "Postdo" function.

                                            *SingleCompile-vim-compiler*
                                            *SingleCompile#SetVimCompiler*
SingleCompile can work with the compiler feature of vim(see |:compiler|). To
set the compiler file in the compiler direcotry for a compiler, use
SingleCompile#SetVimCompiler function. For example, for g77, the GNU Fortran
77 compiler, use the following line to set the compiler file for g77:
>
 call SingleCompile#SetVimCompiler('fortran', 'g77', 'fortran_g77')
<
(This line is excerpted from the built-in templates.)

Then if we are using g77 as our compiler, SingleCompile will first execute
":compiler fortran_g77" before compiling the source file. This will give us
the advantage that vim's quickfix will recognize the messages output by g77
and help us locate these errors quickly.

                                            *SingleCompile-priority*
                                            *SingleCompile#SetPriority*
Since version 2.9, every compiler template could be assigned a priority value.
This value determines which compiler to use when seversal compilers has been
detected. Use the following line to set a compiler's priority:
>
 call SingleCompile#SetPriority('language_name', 'compiler_name', priority)
<
The parameter "priority" is an integer. The less the parameter "priority" is,
the higher priority the compiler has. For example, the following two lines set
two Fortran compilers' priorities (The two lines are excerpted from the
built-in template):
>
 call SingleCompile#SetPriority('fortran', 'gfortran', 70)
 call SingleCompile#SetPriority('fortran', 'ifort', 80)
<
After executing the two lines above, if ifort (which is Intel Fortran
Compiler) and gfortran (GNU fortran compiler) are both detected by
SingleCompile, and the user does not call |SingleCompile#ChooseCompiler| to
choose a compiler explicitly, SingleCompile will choose gfortran as the
current compiler.

CREDITS~
                                            *SingleCompile-credits*
----------------------------------------------------------------------------
Marc Weber  Integrated SingleCompile with vim-addon-actions, and some other
            improvements
Darek       Fixed a directory switching bug
sky hi      Provided DMD compiler for D language built-in template
Zhou Yichao Made several improvements and fixed several bugs.


TODO~
                                            *SingleCompile-todo*
----------------------------------------------------------------------------
Add asynchronous compilation support.

Add matlab built-in template.

If "tee" is used when we are executing ":make" command, currently we can't get
the exit code of the compiler. We need to fix this.

When running compiled program, if "tee" is used for redirecting, things
written to stdout are not printed as if what happens when stdout is a tty.
This need to be fixed.

Make it possible to store compiler template in config files, such as ini
files.

Reduce startup time and shrink memory use.

vim:ts=4:ft=help:tw=78:et