~ubuntu-branches/debian/stretch/ccache/stretch

There are two ways to use ccache\&. You can either prefix your compilation commands with \fBccache\fR or you can create a symbolic link (named as your compiler) to ccache\&. The first method is most convenient if you just want to try out ccache or wish to use it for some specific projects\&. The second method is most useful for when you wish to use ccache for all your compilations\&.

159

.sp

160

To install for usage by the first method just make sure \fBccache\fR is in your path\&.

161

.sp

162

To install for the second method, do something like this:

158

There are two ways to use ccache\&. You can either prefix your compilation commands with \fBccache\fR or you can let ccache masquerade as the compiler by creating a symbolic link (named as the compiler) to ccache\&. The first method is most convenient if you just want to try out ccache or wish to use it for some specific projects\&. The second method is most useful for when you wish to use ccache for all your compilations\&.

159

.sp

160

To use the first method, just make sure that \fBccache\fR is in your \fBPATH\fR\&.

161

.sp

162

To use the symlinks method, do something like this:

163

.sp

164

.if n \{\

165

.RS 4

175

.RE

176

.\}

177

.sp

178

And so forth\&. This will work as long as /usr/local/bin comes before the path to the compiler (which is usually in /usr/bin)\&. After installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link is being used\&.

179

.if n \{\

180

.sp

181

.\}

182

.RS 4

183

.it 1 an-trap

184

.nr an-no-space-flag 1

185

.nr an-break-flag 1

186

.br

187

.ps +1

188

\fBNote\fR

178

And so forth\&. This will work as long as the directory with symlinks comes before the path to the compiler (which is usually in /usr/bin)\&. After installing you may wish to run \(lqwhich gcc\(rq to make sure that the correct link is being used\&.

179

.if n \{\

180

.sp

181

.\}

182

.RS 4

183

.it 1 an-trap

184

.nr an-no-space-flag 1

185

.nr an-break-flag 1

186

.br

187

.ps +1

188

\fBWarning\fR

189

.ps -1

190

.br

191

.sp

192

The technique of letting ccache masquerade as the compiler works well, but currently doesn\(cqt interact well with other tools that do the same thing\&. See USING CCACHE WITH OTHER COMPILER WRAPPERS\&.

193

.sp .5v

194

.RE

195

.if n \{\

196

.sp

197

.\}

198

.RS 4

199

.it 1 an-trap

200

.nr an-no-space-flag 1

201

.nr an-break-flag 1

202

.br

203

.ps +1

204

\fBWarning\fR

189

205

.ps -1

190

206

.br

191

207

.sp

237

253

.RE

238

254

.SH "EXTRA OPTIONS"

239

255

.sp

240

When run as a compiler, ccache usually just takes the same command line options as the compiler you are using\&. The only exception to this is the option \fB\-\-ccache\-skip\fR\&. That option can be used to tell ccache that the next option is definitely not a input filename, and should be passed along to the compiler as\-is\&.

256

When run as a compiler, ccache usually just takes the same command line options as the compiler you are using\&. The only exception to this is the option \fB\-\-ccache\-skip\fR\&. That option can be used to tell ccache to avoid interpreting the next option in any way and to pass it along to the compiler as\-is\&.

241

257

.sp

242

258

The reason this can be important is that ccache does need to parse the command line and determine what is an input filename and what is a compiler option, as it needs the input filename to determine the name of the resulting object file (among other things)\&. The heuristic ccache uses when parsing the command line is that any argument that exists as a file is treated as an input file name\&. By using \fB\-\-ccache\-skip\fR you can force an option to not be treated as an input file name and instead be passed along to the compiler as a command line option\&.

259

.sp

260

Another case where \fB\-\-ccache\-skip\fR can be useful is if ccache interprets an option specially but shouldn\(cqt, since the option has another meaning for your compiler than what ccache thinks\&.

243

261

.SH "ENVIRONMENT VARIABLES"

244

262

.sp

245

263

ccache uses a number of environment variables to control operation\&. In most cases you won\(cqt need any of these as the defaults will be fine\&.

259

277

to force the name of the compiler to use\&. If you don\(cqt do this then ccache works it out from the command line\&.

260

278

.RE

261

279

.PP

280

\fBCCACHE_COMPILERCHECK\fR

281

.RS 4

282

By default, ccache includes the modification time (\(lqmtime\(rq) and size of the compiler in the hash to ensure that results retrieved from the cache are accurate\&. The

283

\fBCCACHE_COMPILERCHECK\fR

284

environment variable can be used to select another strategy\&. Possible values are:

285

.PP

286

\fBcontent\fR

287

.RS 4

288

Hash the content of the compiler binary\&. This makes ccache very slightly slower compared to the

289

\fBmtime\fR

290

setting, but makes it cope better with compiler upgrades during a build bootstrapping process\&.

291

.RE

292

.PP

293

\fBmtime\fR

294

.RS 4

295

Hash the compiler\(cqs mtime and size, which is fast\&. This is the default\&.

296

.RE

297

.PP

298

\fBnone\fR

299

.RS 4

300

Don\(cqt hash anything\&. This may be good for situations where you can safely use the cached results even though the compiler\(cqs mtime or size has changed (e\&.g\&. if the compiler is built as part of your build system and the compiler\(cqs source has not changed, or if the compiler only has changes that don\(cqt affect code generation)\&. You should only use the

301

\fBnone\fR

302

setting if you know what you are doing\&.

303

.RE

304

.PP

305

\fIa command string\fR

306

.RS 4

307

Hash the standard output and standard error output of the specified command\&. The string will be split on whitespace to find out the command and arguments to run\&. No other interpretation of the command string will be done, except that the special word \(lq%compiler%\(rq will be replaced with the path to the compiler\&. Several commands can be specified with semicolon as separator\&. Examples:

308

.sp

309

.RS 4

310

.ie n \{\

311

\h'-04'\(bu\h'+03'\c

312

.\}

313

.el \{\

314

.sp -1

315

.IP \(bu 2.3

316

.\}

317

318

%compiler% \-v

319

.RE

320

.sp

321

.RS 4

322

.ie n \{\

323

\h'-04'\(bu\h'+03'\c

324

.\}

325

.el \{\

326

.sp -1

327

.IP \(bu 2.3

328

.\}

329

330

%compiler% \-dumpmachine; %compiler% \-dumpversion

331

.RE

332

.sp

333

You should make sure that the specified command is as fast as possible since it will be run once for each ccache invocation\&.

334

.sp

335

Identifying the compiler using a command is useful if you want to avoid cache misses when the compiler has been rebuilt but not changed\&.

336

.sp

337

Another case is when the compiler (as seen by ccache) actually isn\(cqt the real compiler but another compiler wrapper \(em in that case, the default

338

\fBmtime\fR

339

method will hash the mtime and size of the other compiler wrapper, which means that ccache won\(cqt be able to detect a compiler upgrade\&. Using a suitable command to identify the compiler is thus safer, but it\(cqs also slower, so you should consider continue using the

340

\fBmtime\fR

341

method in combination with

342

\fBCCACHE_PREFIX\fR

343

if possible\&. See

344

USING CCACHE WITH OTHER COMPILER WRAPPERS\&.

345

.RE

346

.RE

347

.PP

262

348

\fBCCACHE_COMPRESS\fR

263

349

.RS 4

264

350

If you set the environment variable

266

352

then ccache will compress object files and other compiler output it puts in the cache\&. However, this setting has no effect on how files are retrieved from the cache; compressed and uncompressed results will still be usable regardless of this setting\&.

267

353

.RE

268

354

.PP

269

\fBCCACHE_COMPILERCHECK\fR

270

.RS 4

271

By default, ccache includes the modification time (mtime) and size of the compiler in the hash to ensure that results retrieved from the cache are accurate\&. The

272

\fBCCACHE_COMPILERCHECK\fR

273

environment variable can be used to select another strategy\&. Possible values are:

274

.PP

275

\fBcontent\fR

276

.RS 4

277

Hash the content of the compiler binary\&.

278

.RE

279

.PP

280

\fBmtime\fR

281

.RS 4

282

Hash the compiler\(cqs mtime and size\&. This is the default\&.

283

.RE

284

.PP

285

\fBnone\fR

286

.RS 4

287

Don\(cqt hash anything\&.

288

.RE

289

.sp

290

Setting the variable to

291

\fBcontent\fR

292

makes ccache very slightly slower, but makes it cope better with compiler upgrades during a build bootstrapping process\&. The

293

\fBnone\fR

294

setting may be good for situations where you can safely use the cached results even though the compiler\(cqs mtime or size has changed (e\&.g\&. if the compiler is built as part of your build system and the compiler\(cqs source has not changed, or if the compiler only has changes that don\(cqt affect code generation)\&. You should only set the variable to

295

\fBnone\fR

296

if you know what you are doing\&.

297

.RE

298

.PP

299

355

\fBCCACHE_CPP2\fR

300

356

.RS 4

301

357

If you set the environment variable

303

359

then ccache will not use the optimisation of avoiding the second call to the preprocessor by compiling the preprocessed output that was used for finding the hash in the case of a cache miss\&. This is primarily a debugging option, although it is possible that some unusual compilers will have problems with the intermediate filename extensions used in this optimisation, in which case this option could allow ccache to be used anyway\&.

304

360

.RE

305

361

.PP

362

\fBCCACHE_DETECT_SHEBANG\fR

363

.RS 4

364

The

365

\fBCCACHE_DETECT_SHEBANG\fR

366

environment variable only has meaning on Windows\&. It instructs ccache to open the executable file to detect the

367

\fB#!/bin/sh\fR

368

string, in which case ccache will search for

369

\fBsh\&.exe\fR

370

371

\fBPATH\fR

372

and use that to launch the executable\&.

373

.RE

374

.PP

306

375

\fBCCACHE_DIR\fR

307

376

.RS 4

308

377

The

331

400

.RS 4

332

401

If you set the environment variable

333

402

\fBCCACHE_EXTRAFILES\fR

334

to a colon\-separated list of paths then ccache will include the contents of those files when calculating the hash sum\&.

403

to a list of paths then ccache will include the contents of those files when calculating the hash sum\&. The list separator is semicolon in Windows systems and colon on other systems\&.

335

404

.RE

336

405

.PP

337

406

\fBCCACHE_HARDLINK\fR

521

590

.RE

522

591

.sp

523

592

The direct mode is generally faster since running the preprocessor has some overhead\&.

593

.SS "Common hashed information"

594

.sp

595

For both modes, the following information is included in the hash:

596

.sp

597

.RS 4

598

.ie n \{\

599

\h'-04'\(bu\h'+03'\c

600

.\}

601

.el \{\

602

.sp -1

603

.IP \(bu 2.3

604

.\}

605

the extension used by the compiler for a file with preprocessor output (normally

606

\fB\&.i\fR

607

for C code and

608

\fB\&.ii\fR

609

for C++ code)

610

.RE

611

.sp

612

.RS 4

613

.ie n \{\

614

\h'-04'\(bu\h'+03'\c

615

.\}

616

.el \{\

617

.sp -1

618

.IP \(bu 2.3

619

.\}

620

the compiler\(cqs size and modification time (or other compiler\-specific information specified by

621

\fBCCACHE_COMPILERCHECK\fR)

622

.RE

623

.sp

624

.RS 4

625

.ie n \{\

626

\h'-04'\(bu\h'+03'\c

627

.\}

628

.el \{\

629

.sp -1

630

.IP \(bu 2.3

631

.\}

632

the name of the compiler

633

.RE

634

.sp

635

.RS 4

636

.ie n \{\

637

\h'-04'\(bu\h'+03'\c

638

.\}

639

.el \{\

640

.sp -1

641

.IP \(bu 2.3

642

.\}

643

the current directory (if

644

\fBCCACHE_HASHDIR\fR

645

is set)

646

.RE

647

.sp

648

.RS 4

649

.ie n \{\

650

\h'-04'\(bu\h'+03'\c

651

.\}

652

.el \{\

653

.sp -1

654

.IP \(bu 2.3

655

.\}

656

contents of files specified by

657

\fBCCACHE_EXTRAFILES\fR

658

(if any)

659

.RE

524

660

.SS "The direct mode"

525

661

.sp

526

In the direct mode, the hash is formed of:

662

In the direct mode, the hash is formed of the common information and:

527

663

.sp

528

664

.RS 4

529

665

.ie n \{\

547

683

the command line options

548

684

.RE

549

685

.sp

550

.RS 4

551

.ie n \{\

552

\h'-04'\(bu\h'+03'\c

553

.\}

554

.el \{\

555

.sp -1

556

.IP \(bu 2.3

557

.\}

558

the real compiler\(cqs size and modification time (unless

559

\fBCCACHE_COMPILERCHECK\fR

560

says something else)

561

.RE

562

.sp

563

686

Based on the hash, a data structure called \(lqmanifest\(rq is looked up in the cache\&. The manifest contains:

564

687

.sp

565

688

.RS 4

687

810

.RE

688

811

.SS "The preprocessor mode"

689

812

.sp

690

In the preprocessor mode, the hash is formed of:

813

In the preprocessor mode, the hash is formed of the common information and:

691

814

.sp

692

815

.RS 4

693

816

.ie n \{\

722

845

.sp -1

723

846

.IP \(bu 2.3

724

847

.\}

725

the real compiler\(cqs size and modification time (unless

726

\fBCCACHE_COMPILERCHECK\fR

727

says something else)

728

.RE

729

.sp

730

.RS 4

731

.ie n \{\

732

\h'-04'\(bu\h'+03'\c

733

.\}

734

.el \{\

735

.sp -1

736

.IP \(bu 2.3

737

.\}

738

848

any standard error output generated by the preprocessor

739

849

.RE

740

850

.sp

812

922

If you specify an absolute path to the source code file and compile with

813

923

\fB\-g\fR, the source code path stored in the object file may point to the wrong directory, which may prevent debuggers like GDB from finding the source code\&. Sometimes, a work\-around is to change the directory explicitly with the \(lqcd\(rq command in GDB\&.

814

924

.RE

925

.SH "PRECOMPILED HEADERS"

926

.sp

927

ccache has support for GCC\(cqs precompiled headers\&. However, you have to do some things to make it work properly:

928

.sp

929

.RS 4

930

.ie n \{\

931

\h'-04'\(bu\h'+03'\c

932

.\}

933

.el \{\

934

.sp -1

935

.IP \(bu 2.3

936

.\}

937

You must set

938

\fBCCACHE_SLOPPINESS\fR

939

940

\fBtime_macros\fR\&. The reason is that ccache can\(cqt tell whether

941

\fB__TIME__\fR

942

943

\fB__DATE__\fR

944

is used when using a precompiled header\&.

945

.RE

946

.sp

947

.RS 4

948

.ie n \{\

949

\h'-04'\(bu\h'+03'\c

950

.\}

951

.el \{\

952

.sp -1

953

.IP \(bu 2.3

954

.\}

955

You must either:

956

.sp

957

.RS 4

958

.ie n \{\

959

\h'-04'\(bu\h'+03'\c

960

.\}

961

.el \{\

962

.sp -1

963

.IP \(bu 2.3

964

.\}

965

use the

966

\fB\-include\fR

967

compiler option to include the precompiled header (i\&.e\&., don\(cqt use

968

\fB#include\fR

969

in the source code to include the header); or

970

.RE

971

.sp

972

.RS 4

973

.ie n \{\

974

\h'-04'\(bu\h'+03'\c

975

.\}

976

.el \{\

977

.sp -1

978

.IP \(bu 2.3

979

.\}

980

add the

981

\fB\-fpch\-preprocess\fR

982

compiler option when compiling\&.

983

.RE

984

.sp

985

If you don\(cqt do this, either the non\-precompiled version of the header file will be used (if available) or ccache will fall back to running the real compiler and increase the statistics counter \(lqpreprocessor error\(rq (if the non\-precompiled header file is not available)\&.

986

.RE

815

987

.SH "SHARING A CACHE"

816

988

.sp

817

989

A group of developers can increase the cache hit rate by sharing a cache directory\&. To share a cache without unpleasant side effects, the following conditions should to be met:

907

1079

.RE

908

1080

.sp

909

1081

A tip is to set \fBCCACHE_TEMPDIR\fR to a directory on the local host to avoid NFS traffic for temporary files\&.

910

.SH "USING CCACHE WITH DISTCC"

911

.sp

912

\(lqdistcc\(rq is a very useful program for distributing compilation across a range of compiler servers\&. It is often useful to combine distcc with ccache so that compilations that are done are sped up by distcc, but ccache avoids the compilation completely where possible\&.

913

.sp

914

The recommended way of combining distcc and ccache is by using the \fBCCACHE_PREFIX\fR option\&. You just need to set the environment variable \fBCCACHE_PREFIX\fR to \fBdistcc\fR and ccache will prefix the command line used with the compiler with the command \(lqdistcc\(rq\&.

915

.sp

916

It is not recommended to use the form \fBccache distcc compiler args\fR as the compilation command, because ccache will in that case hash the mtime of distcc instead of the compiler (see the \fBCCACHE_COMPILERCHECK\fR option), which means that compiler upgrades will not be detected properly and that the cached results will not be shared between compilations with and without distcc\&.

1082

.SH "USING CCACHE WITH OTHER COMPILER WRAPPERS"

1083

.sp

1084

The recommended way of combining ccache with another compiler wrapper (such as \(lqdistcc\(rq) is by using the \fBCCACHE_PREFIX\fR option\&. You just need to set the environment variable \fBCCACHE_PREFIX\fR to the name of the wrapper (e\&.g\&. \fBdistcc\fR) and ccache will prefix the command line with the specified command when running the compiler\&.

1085

.sp

1086

Unless you set \fBCCACHE_COMPILERCHECK\fR to a suitable command (see the description of that configuration option), it is not recommended to use the form \fBccache anotherwrapper compiler args\fR as the compilation command\&. It\(cqs also not recommended to use the masquerading technique for the other compiler wrapper\&. The reason is that by default, ccache will in both cases hash the mtime and size of the other wrapper instead of the real compiler, which means that:

1087

.sp

1088

.RS 4

1089

.ie n \{\

1090

\h'-04'\(bu\h'+03'\c

1091

.\}

1092

.el \{\

1093

.sp -1

1094

.IP \(bu 2.3

1095

.\}

1096

Compiler upgrades will not be detected properly\&.

1097

.RE

1098

.sp

1099

.RS 4

1100

.ie n \{\

1101

\h'-04'\(bu\h'+03'\c

1102

.\}

1103

.el \{\

1104

.sp -1

1105

.IP \(bu 2.3

1106

.\}

1107

The cached results will not be shared between compilations with and without the other wrapper\&.

1108

.RE

1109

.sp

1110

Another minor thing is that if \fBCCACHE_PREFIX\fR is not used, ccache will needlessly invoke the other wrapper when running the preprocessor\&.

917

1111

.SH "BUGS"

918

1112

.sp

919

1113

.RS 4

1128

1322

.sp -1

1129

1323

.IP \(bu 2.3

1130

1324

.\}

1131

If \(lqpreprocessor error\(rq has been incremented, one possible reason is that precompiled headers are being used\&. ccache currently doesn\(cqt handle that\&.

1132

.RE

1133

.sp

1134

.RS 4

1135

.ie n \{\

1136

\h'-04'\(bu\h'+03'\c

1137

.\}

1138

.el \{\

1139

.sp -1

1140

.IP \(bu 2.3

1141

.\}

1142

1325

If \(lqunsupported compiler option\(rq has been incremented, enable debug logging and check which option was rejected\&.

1143

1326

.RE

1327

.sp

1328

.RS 4

1329

.ie n \{\

1330

\h'-04'\(bu\h'+03'\c

1331

.\}

1332

.el \{\

1333

.sp -1

1334

.IP \(bu 2.3

1335

.\}

1336

If \(lqpreprocessor error\(rq has been incremented, one possible reason is that precompiled headers are being used\&. See

1337

PRECOMPILED HEADERS

1338

for how to remedy this\&.

1339

.RE

1340

.sp

1341

.RS 4

1342

.ie n \{\

1343

\h'-04'\(bu\h'+03'\c

1344

.\}

1345

.el \{\

1346

.sp -1

1347

.IP \(bu 2.3

1348

.\}

1349

If \(lqcan\(cqt use precompiled header\(rq has been incremented, see

1350

PRECOMPILED HEADERS\&.

1351

.RE

1144

1352

.SS "Errors when compiling with ccache"

1145

1353

.sp

1146

1354

If compilation doesn\(cqt work with ccache, but it works without it, one possible reason is that the compiler can\(cqt compile preprocessed output correctly\&. A workaround that may work is to set \fBCCACHE_CPP2\fR\&. This will make cache misses slower, though, so it is better to find and fix the root cause\&.

1154

1362

Credits, mailing list information, bug reporting instructions, source code, etc, can be found on ccache\(cqs web site: http://ccache\&.samba\&.org\&.

1155

1363

.SH "AUTHOR"

1156

1364

.sp

1157

ccache is currently maintained by Joel Rosdahl and was originally written by Andrew Tridgell\&. See http://ccache\&.samba\&.org/credits\&.html for a list of contributors\&.

1365

ccache was originally written by Andrew Tridgell and is currently developed and maintained by Joel Rosdahl\&. See AUTHORS\&.txt or AUTHORS\&.html and http://ccache\&.samba\&.org/credits\&.html for a list of contributors\&.

Older »