docs/siso_tips.md

# Siso Tips

When using Siso, there are a few tips that are particularly useful in
Chromium codebase.

[TOC]

## Compile a single file

Siso/Ninja supports a special [syntax `^`][ninja hat syntax] to compile a single object file specifying
the source file. For example, `autoninja -C out/Default ../../base/logging.cc^`
compiles `obj/base/base/logging.o`.

[ninja hat syntax]: https://ninja-build.org/manual.html#:~:text=There%20is%20also%20a%20special%20syntax%20target%5E%20for%20specifying%20a%20target%20as%20the%20first%20output%20of%20some%20rule%20containing%20the%20source%20you%20put%20in%20the%20command%20line%2C%20if%20one%20exists.%20For%20example%2C%20if%20you%20specify%20target%20as%20foo.c%5E%20then%20foo.o%20will%20get%20built%20(assuming%20you%20have%20those%20targets%20in%20your%20build%20files)

In addition to `foo.cc^`, Siso also supports `foo.h^` syntax to compile
the corresponding `foo.o` if it exists.

On Windows, you need to add  `^^` to preserve the trailing `^`.

```shell
$ autoninja -C out\Default ..\..\base\logging.cc^^
```

If you run a `bash` shell, you can use the following script to ease invocation:

```shell
#!/bin/sh
files=("${@/#/..\/..\/}")
autoninja -C out/Default ${files[@]/%/^^}
```

This script assumes it is run from `src` and your output dir is `out/Default`;
it invokes `autoninja` to compile all given files. If you place it in your
`$PATH` and name it e.g. `compile`, you can invoke like this:

```shell
$ pwd  # Just to illustrate where this is run from
/c/src
$ compile base/time/time.cc base/time/time_unittest.cc
...
[0/47] 5.56s S CXX obj/base/base/time.obj
...
[2/3] 9.27s S CXX obj/base/base_unittests/time_unittest.obj
...
```

## Preferred command line flags

If you keep using the same command line flags, you can put it in
`build/config/siso/.sisorc`.  It is in `.gitignore` and not modified
by any tool.

In `.sisorc`, each line specify the command line flags
for the siso's subcommand.

e.g.
```
ninja -k=0 --verbose_failures=0
```

Then `siso ninja` or `autoninja` will use `-k=0 --verbose_failures=0`
even if you don't specify it on command line.  Your command line
will be added after the command line flags in `.sisorc` and
later flags are effective.

## Limit concurrencies

Siso automatically sets appropriate concurrencies, but
if you want to specify them explicitly, you can use the followings

### `--remote_jobs`

`--remote_jobs` sets maximum number of concurrent remote jobs.

### `--local_jobs`

`--local_jobs` sets maximum number of concurrent local jobs.

### `autoninja -j`

`autoninja` sets `--remote_jobs` from `-j` if remote is enabled,
or sets `--local_jobs` from `-j` if remote is disabled and
number is not larger than number of cpus.

### `SISO_LIMITS`

You can specify other limits by using `SISO_LIMITS` environment
variables.
See [SISO_LIMITS documents](https://chromium.googlesource.com/build/+/refs/heads/main/siso/docs/environment_variables.md#siso_limits).

## Make sure remote steps works.

Siso may run steps locally even if step can run remotely to
make better use of local resources, but it makes it difficult
to check how step runs with remote execution.

`--strict_remote` won't run step locally if it is configured
to use remote.

## Temporary disable remote.

Use `--offline`.

## Run steps as much as possible.

Siso will stop building if it detects step failure.
If you want to run steps as much as possible to see
all error messages at once, use `-k=0` as Ninja.

## Check step's error messages.

Siso records steps output in `siso_output` files,
so you can read it later even if error messages
scrolled out.

You can also use `--verbose_failures=false` to
reduce command line in console output.

For AI agents or so, `--quiet` would be useful.

## Rerun steps even if outputs seems to be up-to-date.

Use `--clobber`.

## Siso ignores local modified output files?

Siso makes sure output files are generated by sources, but there
are cases that are convenient to modify output files locally
and see how build works.

`--fs_keep_tainted` will keep modified output files.

## Use siso other than third_party/siso/cipd/siso

Set the siso binary path in environment variable `SISO_PATH`,
so `depot_tools/siso` use it instead of `third_party/siso/cipd/siso`.