siso for Debian
===============

This package is maintained with git-buildpackage(1) and pristine-tar(1).
The repository is at https://salsa.debian.org/go-team/packages/siso

Upstream source
---------------

siso is part of the Chromium "build" repository at:
  https://chromium.googlesource.com/build/+/refs/heads/main/siso/

It lives in a subdirectory, not a standalone repository. Upstream releases
are tagged as siso/vX.Y.Z in the build repo.

The orig tarball is created from the upstream git tag using Mode: git in
debian/watch, with Files-Excluded in debian/copyright to keep only the
siso/ and kajiya/ directories plus the LICENSE file. The result is a +ds
repacked tarball.

kajiya (go.chromium.org/build/kajiya) is Chromium's local REAPI test
server, living in the same repository as siso. It is included in the
orig tarball rather than vendored in debian/vendor/.

Obtaining the orig tarball
--------------------------

uscan and debian/watch handle downloading automatically:

  uscan --download-current-version

The watch file uses Mode: git to clone the upstream build repo and
match siso/vX.Y.Z tags. mk-origtargz applies Files-Excluded and adds
the +ds suffix. pristine-tar stores the exact tarball metadata so it
can be reproduced from git.

To import a new upstream version:

  uscan --download
  gbp import-orig --pristine-tar ../siso_NEWVERSION+ds.orig.tar.xz

Tarball layout
--------------

The +ds tarball contains:

  siso-VERSION/
    LICENSE
    siso/          -- siso source (main.go, auth/, build/, ...)
    kajiya/        -- REAPI test server library
    remote-apis/   -- Remote Execution API protos (incorporated upstream)

XS-Go-Import-Path is set to go.chromium.org/build (the parent module)
so dh-golang places siso/ and kajiya/ at the correct GOPATH paths.
The --buildsystem=golang flag is passed explicitly to dh because there
is no go.mod at the tarball root.

Vendoring
---------

As of v1.5.19, no Go dependencies are vendored. All Go dependencies are
available in Debian and listed in Build-Depends.

Previously (v1.5.16 and earlier), three modules were vendored in
debian/vendor/ (bazelbuild/reclient, bazelbuild/remote-apis-sdks,
protoc-gen-bq-schema). Upstream dropped reproxy integration support in
v1.5.19, removing the need for these modules.

Third-party JavaScript
----------------------

The built-in web UI (siso webui) uses Material Web Components from
siso/third_party/material_web_components/components-chromium/node_modules/.

The lit library family (lit, lit-html, lit-element, @lit/reactive-element,
@lit-labs/ssr-dom-shim) is excluded from the orig tarball via
Files-Excluded and provided at build time by the node-lit Debian package.
The files are copied (not symlinked) into the build tree because go:embed
does not follow symlinks.

@lit/task (3 small files) remains in the orig tarball because it is not
included in node-lit.

@material/web CSS-in-JS files (long lines of CSS template literals) are
the upstream source form, not minified code.

Differences from upstream
------------------------

This Debian package removes two Google Cloud-specific features that
require Go modules not packaged in Debian:

  1. OTel Collector subcommand ("siso collector") -- an internal-helper
     for running Google's OpenTelemetry Collector daemon. Only useful
     within Google Cloud infrastructure. Pulls in the entire
     go.opentelemetry.io/collector framework.

  2. Direct Google Cloud Monitoring export -- sends build metrics
     directly to Google Cloud Monitoring via the GCP-proprietary
     cloudmetric API. Requires GCE credentials and project configuration.

Build metrics export via the standard OTLP gRPC protocol is preserved.
Users who need metrics can point siso at any OpenTelemetry-compatible
collector (Grafana, Jaeger, Prometheus, etc.) using --collector_address.

All core functionality is fully preserved:
  - Ninja-compatible builds (siso ninja -C out/Default)
  - Local execution
  - Remote Build Execution (RBE) via --credential_helper
  - Starlark-based build configuration
  - Web UI (siso webui)
  - Build investigation tools (query, report, metrics, recall)

Users who need the full Google Cloud integration should use the upstream
binary distributed via CIPD.

Patches
-------

0001-disable-otel-collector-subcommand.patch:
  Removes the collector subcommand import/registration from main.go and
  replaces the GCP Cloud Monitoring direct exporter in subcmd/ninja/o11y.go
  with an error fallback. The OTLP gRPC exporter path remains functional.

0002-fix-32bit-rusage-int-types.patch:
  Fixes int type overflow on 32-bit architectures (i386, armhf) in
  rusage resource tracking code.

0003-add-man-subcommand.patch:
  Backport of upstream CL 7867164 (Richard Wang). Adds "siso man"
  subcommand for auto-generating the man page from registered subcommands
  and flags. Can be dropped when CL 7867164 is merged upstream.

Test suite
----------

The test suite excludes packages that require:

  - Network access (auth, fetch, proxy)
  - Remote Build Execution infrastructure (e2etests, reapitest)
  - Google Cloud services (resultstore, trace)

On 32-bit architectures, toolsupport/ninjautil tests are also excluded
due to a Go runtime GC crash with the 32 MB nodeMap allocation.
See https://reproduce.debian.net/i386/api/v1/builds/213968/log

Building
--------

Recommended: use gbp buildpackage or sbuild with --chroot-mode=unshare.

  dpkg-source -b siso && sbuild --chroot-mode=unshare --dist=unstable \
    siso_VERSION+ds-REV.dsc
