docs/siso_tips.md - chromium/src.git - Git at Google

 # 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
 ...
 ```

 ## Build gn target

 GN emits phony target for a gn target label, dropping `//`-prefix,
 e.g. `base:base` for `//base:base`, which is `base` target in `base/BUILD.gn`,
 so you can use this as a build target.

 ```shell
 $ autoninja -C out/Default base:base
 ```

 ## 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.

 If build failed, Siso remembers what targets failed
 and tried to rebuild the failed targets first to
 focus on fixing the failure targets with quick iterations.
 To disable this feature, use `-batch` or
 `-fast_last_failure=false` (available since siso v1.4.11).

 ## 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 current release version.

 If you want to use different CIPD version than `siso_version` in `DEPS`,
 you can use `custom_vars` in `.gclient`.

 e.g. To use the latest, non-released version,

 ```
 solutions = [
  {
     "name": "src",
     "url": "https://chromium.googlesource.com/chromium/src.git",
     ...,
     "custom_vars": {
        "siso_version": "latest",
        ...
     },
  },
 ]
 ```

 or to use specific version,

 ```
       # Git revision is for https://chromium.googlesource.com/build repo,
       # and the CIPD package for the git revision needs to be exist in
       # https://chrome-infra-packages.appspot.com/p/build/siso
       "siso_version": "git_revision:<git_revision>",
 ```

 Once you modified `.gclient`, run `gclient sync`.

 Or if you might want to pin depot_tools version (for autoninja, siso
 wrapper), checkout specific version of depot_tools, and run
 `update_depot_tools_toggle.py --disable`.

 If you want to use locally built Siso, Set the siso binary path in
 environment variable `SISO_PATH`, so `depot_tools/siso` use it instead
 of `third_party/siso/cipd/siso`.

 e.g.

 ```shell
 $ export SISO_PATH=$HOME/go/bin/siso
 ```
	# 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
	...
	```

	## Build gn target

	GN emits phony target for a gn target label, dropping `//`-prefix,
	e.g. `base:base` for `//base:base`, which is `base` target in `base/BUILD.gn`,
	so you can use this as a build target.

	```shell
	$ autoninja -C out/Default base:base
	```

	## 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.

	If build failed, Siso remembers what targets failed
	and tried to rebuild the failed targets first to
	focus on fixing the failure targets with quick iterations.
	To disable this feature, use `-batch` or
	`-fast_last_failure=false` (available since siso v1.4.11).

	## 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 current release version.

	If you want to use different CIPD version than `siso_version` in `DEPS`,
	you can use `custom_vars` in `.gclient`.

	e.g. To use the latest, non-released version,

	```
	solutions = [
	{
	"name": "src",
	"url": "https://chromium.googlesource.com/chromium/src.git",
	...,
	"custom_vars": {
	"siso_version": "latest",
	...
	},
	},
	]
	```

	or to use specific version,

	```
	# Git revision is for https://chromium.googlesource.com/build repo,
	# and the CIPD package for the git revision needs to be exist in
	# https://chrome-infra-packages.appspot.com/p/build/siso
	"siso_version": "git_revision:<git_revision>",
	```

	Once you modified `.gclient`, run `gclient sync`.

	Or if you might want to pin depot_tools version (for autoninja, siso
	wrapper), checkout specific version of depot_tools, and run
	`update_depot_tools_toggle.py --disable`.

	If you want to use locally built Siso, Set the siso binary path in
	environment variable `SISO_PATH`, so `depot_tools/siso` use it instead
	of `third_party/siso/cipd/siso`.

	e.g.

	```shell
	$ export SISO_PATH=$HOME/go/bin/siso
	```