Extract common header setup code to functions

Add checksumming of cached content

Both compressed and uncompressed content are checksummed and verified.
The chosen checksum algorithm is XXH64, which is the same that the zstd
frame format uses (but ccache stores all 64 bits instead of only 32,
because why not?).

Require libzstd and remove zlib support

* zlib has been removed. Good riddance!
* libzstd is now required for building ccache. However, it’s not bundled
  like zlib was.
* To make it easier to build ccache on systems that lack an easily
  installable libzstd, the configure script now offers a
  --with-libzstd-from-internet option, which downloads a zstd source
  release archive, unpacks it in the tree and sets up the Makefile to
  build the library and link ccache (statically) with it.
* Enabled compression by default.
* Made compression level 0 mean “use a default level suitable for the
  current compression algorithm”. For zstd, that’s initially level -1,
  but that could change in the future. The reason for using 0 as a
  special marker is that a future alternative compression algorithm
  could have another reasonable default than zstd. (Let’s hope that
  future algorithms don’t use level 0 for something.)
* Changed default compression level to 0.

Closes #413.

Enable build command verbosity in Travis builds

This makes it much easier to understand build failures.

Restructure Travis configuration

In preparation for switching from zlib to zstd. I find it easier to use
a flat job list instead of a matrix and state settings explicitly for
the different jobs.

Don’t enable unit test verbosity in Travis

It’s way too spammy.

Refactor functions for reading/writing common header

The functions now work on bytes instead of FILEs, allowing for the
caller to optionally peek at read/written bytes.

Replace murmurhashneutral2 with xxHash (XXH64)

XXH64 is significantly faster than murmurhashneutral2 (on 64-bit
systems, which one can assume ccache almost always is running on these
days). This of course doesn’t matter for keys in hash tables, but it
opens up for using it as a checksumming algorithm for cached data as
well.

Don’t try a higher zstd level than supported

If the user tries a higher level than supported by libzstd,
initialization will fail. Instead, let’s clamp the level to the highest
supported value.

Regarding negative levels: They are supported from libzstd 1.3.4, but
the query function ZSTD_minCLevel is only supported from 1.4.0 (from
1.3.6 with ZSTD_STATIC_LINKING_ONLY), so let’s not use it for
verification of the level. In libzstd 1.3.3 and older, negative levels
are silently converted to the zstd’s default level (3), so there’s no
major harm done if a user uses a negative level with older libzstd
versions.

Allow for negative compression level

Use the compression API for reading and writing manifests

* Manifest and result files now share the same common header (sans the
  magic bytes) and will be compressed using the common compression
  settings.
* Removed the legacy “hash size” and “reserved” fields.

Tweak code style

Extract and implement more bytes from/to int macros

Improve order of parameters to common_header_*_file

Extract header code common to result and manifest files

Allow using zstd compresssion instead of zlib (#437)

Verify value in “ccache -o key=value”

Based on a suggestion by Henri Houder.

const-ify parameters to confitem verifier/formatter

Change to looser compression_type data type

This avoids a Clang analyzer warning.

Rename “filelist” to “result_files”

Refactor compression type/level calculation

In preparation for introducing a new manifest format.

Add a content size field to the result file header

The content size field says how much uncompressed data is stored in the
file. This can be used to relatively quickly determine the compression
rate for the whole cache by only inspecting each file’s header insted of
having to read and decompress all files.

Since the content size needs to be calculated before actually adding the
content to the result file, I’ve reverted back to let the format use a
“number of entries” field instead of an EOF marker (similar to Anders
Björklund’s original work in 0399be2d) since the information about the
number of files now has to be known beforehand.

Another subtle change is that the compression level field now is int8_t
instead of uint8_t to make it possible to record negative levels.

Don’t try to parse unimplemented reference entries in result files

Remove now unused x_fstat function

Fix check of destination fd in copy_file

Fix possible NULL pointer dereference (#433)

cppcheck:
  [src/manifest.c:270] -> [src/manifest.c:269]: (warning)
  Either the condition '!errmsg' is redundant or there is possible null pointer
  dereference: errmsg.

Improve naming of things

Some words are being used to mean several things in the code base:

* “object” can mean both “the object file (.o) produced by the compiler”
  and “the result stored in the cache, including e.g. the .o file and .d
  file”.
* “hash” can mean both “the state that the hash_* functions operate on”,
  “the output of a hash function” and “the key used to index results
  and manifests in the cache”.

This commits tries to make the naming more consistent:

* “object” means “the object file (.o) produced by the compiler”
* “result” means “the result stored in the cache, including e.g. the .o
  file and .d file”.
* “struct hash” means “the state that the hash_* functions operate on”.
* “digest” means “the output of a hash function”. However, “hash” is
  still used in documentation and command line output since I think that
  “hash” is easier to understand for most people, especially since
  that’s the term used by Git.
* “name” means “the key used to index results and manifests in the
  cache”.

Improve how <MD4, number of hashed bytes> is represented

Internally, the tuple <MD4 hash, number of hashed bytes>,which is the
key used for cached results and manifests, was represented as 16 bytes +
1 uint32_t. Externally, i.e. in file names, it was represented as
<MD4>-<size>, with <MD4> being 32 hex digits and <size> being the number
of hashed bytes in human-readable form.

This commits changes the internal representation to 20 bytes, where the
last 4 bytes are the number of hashed bytes in big-endian order. The
external representation has been changed to match this, i.e. to be 40
hex digits. This makes the code slightly less complex and more
consistent. Also, the code that converts the key into string form has
been rewritten to not allocate on the heap but to just write the output
into a buffer owned by the caller.

struct file_hash (16 bytes + 1 uint32_t) has been renamed to struct
digest (20 bytes) in order to emphasize that it represents the output of
a hash algorithm that not necessarily gets file content as its input.

The documentation of the manifest format has been updated to reflect the
logical change of keys, even though the actual serialized content of
manifest files hasn’t changed. While at it, reading of the obsolete
“hash_size” and “reserved” fields has been removed. (Future changes in
the manifest format will be handled by just stepping the version.)

Add binary representation of hash-size (#399)

* Add binary representation of hash-size

Fixed size efficient binary representation data,
instead of the variable size hexadecimal string.

This is suitable for machine use, while the other
is more suitable for human readability as string.

* Promote hex format as a global function

* Add unittest for the format_hex function

Make sure that output is NUL-terminated

Remove the hard link mode

Rationale:

* The hard link feature is prone to errors: a) changes to files outside
  the cache will corrupt the cache, and b) the mtime field in the file's
  i-node is used for different purposes by ccache and build tools like
  make.
* The upcoming enabling of LZ4 compression by default will make the hard
  link mode obsolete as a means of saving cache space.
* Not supporting hard links will make a future backend storage API
  simpler.

Move mtime update into result_get/manifest_get

Housekeeping of cached files belongs to the backend code, not the
frontend.

Remove now superfluous test of empty result file

Empty files are detected as corrupted by result_get.

Improve error reporting from read_result

“ccache --dump-result” now prints the actual error.

Improve names of result functions and variables

Improve error handling of (de)compressors

Previously, some kinds of corruption were not detected by the zlib
decompressor since it didn’t check that it had reached the end of the
stream and therefore didn’t verify the Adler-32 checksum.

Remove redundant cc_log

Clean up internal trace code

Remove obsolete decompression code

* Remove obsolete decompression functionality from copy_file.
* Removed obsolete move_uncompressed_file.
* Improved return values of copy_file/move_file.

Remove obsolete file_is_compressed function

Uncrustify code

Use the compression API for results

It didn’t feel right to use zlib’s gzip format for the embedded content,
especially since other compression libraries don’t support a similar
interface. Therefore, use the standard low-level zlib API instead.

Add compression interface and none/zlib implementations

Revise disk format for results

* Removed unused hash_size and reserved fields. Since there are no
  hashes stored in in the result metadata, hash size is superfluous. The
  reserved bits field is also unnecessary; if we need to change the
  format, we can just step RESULT_VERSION and be done with it.
* Instead of storing file count in the header, store an EOF marker after
  the file entries. The main reason for this is that files then can be
  appended to the result file without having to precalculate how many
  files the result will contain.
* Don’t include trailing NUL in suffix strings since the length is known.
* Instead of potentially compressing the whole file, added an
  uncompressed header telling how/if the rest of the file is
  compressed (which algorithm and level). This makes it possible to more
  efficiently recompress files in a batch job since it’s possible to
  reasonably efficiently check if a cached file should be repacked. The
  reason for not having compression info in each subfile
  header (supporting different compression algorithms/levels per
  subfile) is to make the repacking scenario simpler.
* Prepared for adding support for “reference entries”, which refer to
  other results. There are two potential use cases for reference
  entries: a) deduplication and b) storing partial results with a
  different compression algorithm/level. It’s probably only the
  deduplication use case that is interesting, though. It can be done
  either at cache miss time or later as a batch job. If we really want
  to, we can in the future add similar “raw reference entries” that
  refer to files stored verbatim in the storage, thus re-enabling hard
  link functionality.
* Changed to cCrS as the magic bytes for result files. This is analogous
  to the magic bytes used for manifest files.
* Added documentation of the format.

Remove --enabled-aggregated feature toggle

Fix temp file leak in --enabled-aggregated mode

Check and act on return value from cache_get

Otherwise corrupted result files won’t get detected.

Remove superfluous dup() call when reading cached result

Add missing argument to stats_update_size

This makes --enabled-aggregated work after being rebased to 0b3276d5.

Add aggregated file storing all the results (#408)

* Add aggregated file storing all the results

* Add dump result method, for viewing binary

Just show sizes, not contents

* Check the results rather than cache contents

This helps when changing the cache storage

* Rename cache struct to filelist instead

Now that it doesn't really store anything

* Add version and hash size to result header

* Copy files by buffer instead of by byte

* Make aggregated result files optional

This will guard the tests, until ready to integrate

* Fix clang warning about unused macros

* Stray comma in configure broke the Mac build

* Avoid freeing the provided structure

* Avoid getting result from cache twice

* Fix partial read/write after rewrite

* Add test cases for aggregated result

* Fix wrong suffix for the depend file

* Read the .stderr with the rest of result

* Fix test suite only being run for clang

* Respect the compression level for result

refactor: Save tmp stderr until done storing (#428)

We might need it for the alternate codepaths

If not using a standard file store, it might
not be possible to move stderr instead of copy.

For those cases, use the temporary file instead.

Improve solution to #405

Instead of changing the global stats_file value temporarily in
update_manifest, pass which file to update explicitly to
stats_update_size.

Remove .xml files in the doc directory on “make distclean”

Mention xsltproc in INSTALL.md

Related to #425.

Tweak formatting of manual text and code comments

Fix PCH detection in depend mode (+test improvements) (#427)

* do not refer to Clang's PTH in tests

The PTH feature has been removed (https://reviews.llvm.org/D54547)
and according to the commit it has never really been used. Maybe this
made sense somewhen in the past, but now those .pth files must be PCHs
internally. This commit actually just changes the .pth extensions
to .pch to avoid confusion, technically nothing should change
except for filenames.

* try to share PCH tests between GCC and Clang

Clang is supposed to be a drop-in for GCC, so in general it should
be able to handle everything GCC can. That's not completely true
in practice, there are differences, but it doesn't make sense
to completely duplicate a testcase just because there are some
differences. So start creating a shared common base for the PCH
tests and do separately only tests that act differently.

* more sharing of PCH tests between GCC and Clang

There's e.g. no need to do all kinds of complex tests with both
.gch and .pch with Clang, except for checking that Clang finds
one of them if none is specified explicitly.

* log also when pch usage is detect from pragma pch_preprocess

* try harder to verify in tests that ccache detects PCH changes

Some of the tests did that, e.g. those 'file changed', but e.g. the cached
.gch creation did not. So try to intentionally change the .gch/.h and test
that it leads to a cache miss. Otherwise there might be a hit simply
because ccache failed to detect PCH usage and ignores the .gch completely.

* clean up #include vs -fpch-preprocess in pch tests

As the manpage says, -fpch-preprocess is needed only with the #include
form, otherwise it's pointless.

* do not mention sloppiness in pch tests, only no sloppiness

Since sloppiness is normally required, so no point in stating the obvious.

* test also -include-pch with clang

* hash also pch introduced only using -include

GCC does not output the pch in the .d dependencies file, so without
this there would be false cache hits.

* be consistent about sloppiness in pch tests

create pch -> pch_defines
use pch -> time_macros

* test CCACHE_PCH_EXTSUM more thoroughly and also with -include

* pch test for .gch file being in an extra directory

* doc corrections for how to use PCH with ccache

- ccache will fail to properly detect that -include a.h means using
  a.h.gch if it requires using path from -I (they are not searched)
- -fpch-preprocess does nothing with Clang, it doesn't output
  pragma GCC pch_preprocess and so #include form for PCHs doesn't work

* explain better problems of -MD/-MMD in depend mode

Hint about not running autogen.sh when building from release archive

Related to #418.

Tweak issue templates

Improve CONTRIBUTING.md and pull request template

Clean up detection of CI environment

“RUN_FROM_BUILD_FARM” was set by the old Samba build farm, so switch to
checking “TRAVIS” instead. Also, keep running in dev mode in Travis.

clang's -ftime-trace is too hard (#424)

It produces extra .json file with timing information about the compilation.

Fix make check with "funny" locales (#420)

'ch' in cs_CZ locale is technically just one character, so directory
name 'ccache' fails the test

Improve manual text for logging to syslog

As discussed in #409.

Implement optional logging to syslog (#409)

* Add syslog implementation, for the log_file

The file logger has some issues with large log lines and many jobs,
so provide the "syslog" alternative when doing the ccache logging.

* Add docs on how to filter with rsyslogd(8)

Improve performance script

* Measure per-call times instead of totals.
* Use median value instead of mean value.

Add pull request template

Tweak feature request issue template

Handle unknown manifest version gracefully in --dump-manifest

Previously “ccache --dump-manifest file” would crash with an assert when
the file did not have the expected version.

Change order of file size and hashed size in manifest

I think that it makes sense to keep hash digest and hashed bytes next to
each other since they are related.

Also:

* Renamed hashed_content_size to hsize and size to fsize.
* Fixed long source lines.

Fix object size verification + bump to 64 bit file sizes in manifest (#407)

Changed manifest format to save the actual file size along with hashed content size.
File size field in manifest updated to 64bits.
Manifest version set to 2.

Fixes #382.

Refine “about” for the support issue template

Tweak issue templates

Add support question template

Add feature request template

Improve bug report template

Add bug report template

Tweak comment

Update the correct stats file for manifest (#405)

There are global variables used for updating stats,
and those were wrong for the manifest file update.

So make sure to reset those variables, before adding
the manifest (this means flushing the pending updates)

Fix source comment and documentation typos (#403)

Found via `codespell -q 3 -L uint,thru -S ./src/zlib`

Prepare for v3.7.1

Prepare for v3.7.1

Avoid -Wextra-semi-stmt warnings from Clang

Update NEWS

Fix usage of ferror after fclose

Improve fix in #400 to handle more cases

The dependency file name can come from e.g. DEPENDENCIES_OUTPUT as well,
so hash information about a /dev/null .d file after the argument
processing loop instead.

Tweak code style

Hash information to make results with -MF /dev/null unique (#400)

If we first run with -MF /dev/null, then we will get a
"cache file missing" error on the next run - avoid that.

Make sure to cache the special /dev/null value, so that
it differs from the normal (ignored) dep file name...

Revert "Bail out on “-MF /dev/null”"

This reverts commit 253301e7ac56a9d2bed1f03a91ba73be102a0d42.

Bail out on “-MF /dev/null”

This is an alternative fix for #397, based on the observation/assumption
that using “-MF /dev/null” is only ever used as part of a compiler probe
call in combination with “-c /dev/null -o /dev/null”, so there is little
reason to cache the result. The advantage of just bailing out is to
reduce the number of special cases we have to handle.

Fix “Help wanted”/”Good first issues” links

Support using -MF /dev/null argument (#398)

This is sometimes used when detecting capabilities.

Sort entries in LICENSE.adoc

Make uncrustify ignore newlines for enums

Uncrustify doesn’t properly understand enums as return values and
ignoring newlines is an easy workaround.

Tweak typedef of the stat format function

Typedef-ing the function as a pointer type works better with uncrustify.

Calculate length correctly in win32argvtos

Fix NULL argument in profile directory trace (#395)

With -fprofile-*=path, we currently print :
"Setting profile directory to (null)".

This fixes the build with gcc 9, which failed with :
error: ‘%s’ directive argument is null [-Werror=format-overflow=]

Fix memory and temporary file leak

Fix code style

Handle @file syntax on Windows correctly (#392)

* add length return to win32argvtos()

this is useful for determining the length of the generated argument string

* correctly handle @file syntax on Windows

the @file syntax means that the process reads command arguments from the
specified file. this is commonly used in order to shorten commands which
would otherwise be longer than the maximum length limit: many build systems
do this in all cases to avoid hitting this limit.

when a command exceeds 8192 characters on on Windows, ccache now writes
the parsed/modified arguments to a tmpfile and then runs the command using
that tmpfile with @tmpfile in order to preserve this mechanism and avoid hitting
the length limit

fixes #95

Prepare for v3.7

Don’t include email addresses in authors list

Not all users have real email addresses anyway, and I don’t see any real
use for maintaining a “correct” list of addresses.