<commit_before>clcache.py - a compiler cache for Microsoft Visual Studio
---------------------------------------------------------

clcache.py is a little Python script which attempts to avoid unnecessary
recompilation by reusing previously cached object files if possible. It
is meant to be called instead of the original 'cl.exe' executable. The
script analyses the command line to decide whether source code is
to be compiled. If so, a cache will be queried for a previously stored
object file.

If the script is called in an unsupported way (multiple source files in
one invocation, compiler called for linking), the script will simply
relay the invocation to the real 'cl.exe' program.

image:https://ci.appveyor.com/api/projects/status/sf98y2686r00q6ga/branch/master?svg=true[Build status, link="https://ci.appveyor.com/project/frerich/clcache"]
image:https://codecov.io/gh/frerich/clcache/branch/master/graph/badge.svg[Code coverage, link="https://codecov.io/gh/frerich/clcache"]
image:https://www.quantifiedcode.com/api/v1/project/652606d7e4a94db0bf2da6f0e5778c94/badge.svg[Code issues, link="https://www.quantifiedcode.com/app/project/652606d7e4a94db0bf2da6f0e5778c94"]

Installation
~~~~~~~~~~~~

Python 3.3+ is required.

You can generate a self-contained 'clcache.exe' file using
http://www.pyinstaller.org[PyInstaller]. If you don't have it already,
installing PyInstaller is usually a matter of running

    pip install pyinstaller

Afterwards, you can generate an executable by running

    pyinstaller --onefile clcache.py

This will put the resulting binary and all the dependencies into a 'dist\\'
subdirectory.  You could then tell your build system to use 'clcache.exe' as
the compiler binary, or you could rename 'clcache.exe' to 'cl.exe' and put it
into a directory which comes first in the +PATH+. In my case, I went for the
latter solution; I put the 'cl.exe' binary into '%HOME%\bin' and prepended that
directory to the +PATH+.  The 'cl.exe' wrapper binary will notice that it was
renamed and forward all the arguments to the real compiler executable.

This way, simply running 'cl' will invoke the script instead of the real
compiler.

Installation For Visual Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some users have reported (see e.g. GitHub issue #18) that in order to make Visual Studio pick up `clcache`, the original compiler binary needs to be moved out of the
way and replaced with the executable generated via the `py2exe` script:

1. Rename `cl.exe` to e.g. `cl_original.exe`
2. Rename `cl.exe.config` to e.g. `cl_original.exe.config`
3. Copy `clcache.exe` to `cl.exe`
4. Set `CLCACHE_CL` environment variable to point to `cl_original.exe`.

Options
~~~~~~~

--help::
    Print usage information
-s::
    Print some statistics about the cache (cache hits, cache misses, cache
    size etc.)
-c::
    Clean the cache: trim the cache size to 90% of its maximum by removing<commit_msg>Document alternative installation via clcache.bat<commit_after>clcache.py - a compiler cache for Microsoft Visual Studio
---------------------------------------------------------

clcache.py is a little Python script which attempts to avoid unnecessary
recompilation by reusing previously cached object files if possible. It
is meant to be called instead of the original 'cl.exe' executable. The
script analyses the command line to decide whether source code is
to be compiled. If so, a cache will be queried for a previously stored
object file.

If the script is called in an unsupported way (multiple source files in
one invocation, compiler called for linking), the script will simply
relay the invocation to the real 'cl.exe' program.

image:https://ci.appveyor.com/api/projects/status/sf98y2686r00q6ga/branch/master?svg=true[Build status, link="https://ci.appveyor.com/project/frerich/clcache"]
image:https://codecov.io/gh/frerich/clcache/branch/master/graph/badge.svg[Code coverage, link="https://codecov.io/gh/frerich/clcache"]
image:https://www.quantifiedcode.com/api/v1/project/652606d7e4a94db0bf2da6f0e5778c94/badge.svg[Code issues, link="https://www.quantifiedcode.com/app/project/652606d7e4a94db0bf2da6f0e5778c94"]

Installation
~~~~~~~~~~~~

Python 3.3+ is required.

Installation via exe
^^^^^^^^^^^^^^^^^^^^

You can generate a self-contained 'clcache.exe' file using
http://www.pyinstaller.org[PyInstaller]. If you don't have it already,
installing PyInstaller is usually a matter of running

    pip install pyinstaller

Afterwards, you can generate an executable by running

    pyinstaller --onefile clcache.py

This will put the resulting binary and all the dependencies into a 'dist\\'
subdirectory.  You could then tell your build system to use 'clcache.exe' as
the compiler binary, or you could rename 'clcache.exe' to 'cl.exe' and put it
into a directory which comes first in the +PATH+. In my case, I went for the
latter solution; I put the 'cl.exe' binary into '%HOME%\bin' and prepended that
directory to the +PATH+.  The 'cl.exe' wrapper binary will notice that it was
renamed and forward all the arguments to the real compiler executable.

This way, simply running 'cl' will invoke the script instead of the real
compiler.

Installation for Visual Studio
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Some users have reported (see e.g. GitHub issue #18) that in order to make Visual Studio pick up `clcache`, the original compiler binary needs to be moved out of the
way and replaced with the executable generated via the `py2exe` script:

1. Rename `cl.exe` to e.g. `cl_original.exe`
2. Rename `cl.exe.config` to e.g. `cl_original.exe.config`
3. Copy `clcache.exe` to `cl.exe`
4. Set `CLCACHE_CL` environment variable to point to `cl_original.exe`.

Alternative installation via clcache.bat
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This method is especially handy when there are multiple Python installations
on a system.

Create a clcache.bat and put it in a directory in PATH (e.g. %HOME%\bin):

    @echo off
    @setlocal
    rem this is a good place for clcache environment variables
    set CLCACHE_HARDLINK=1
    C:\Python35\python.exe C:\clcache\clcache.py %*

Now set your compiler to `clcache.bat` in the build system, e.g. for cmake

    set CC=clcache.bat
    set CXX=clcache.bat
    cmake ...
    nmake

Check stats via `clcache.bat -s`, clear cache `clcache.bat -C` and so on.

Options
~~~~~~~

--help::
    Print usage information
-s::
    Print some statistics about the cache (cache hits, cache misses, cache
    size etc.)
-c::
    Clean the cache: trim the cache size to 90% of its maximum by removing
{'fraction_non_alphanumeric': 0.11721611721611722, 'fraction_numerical': 0.01907814407814408, 'mean_word_length': 4.013771996939556, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 12, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '56972', 'n_tokens_mistral': 2028, 'n_tokens_neox': 1895, 'n_words': 803}