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

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.

Partial vendoring (debian/vendor/)
----------------------------------

Per Debian Go team policy, dependencies available in Debian are used via
Build-Depends and are NOT vendored. Only dependencies not yet packaged in
Debian are kept in debian/vendor/ (following the same pattern used by
containerd and usql in Debian).

The package uses dh-golang in GOPATH mode. System packages are symlinked
from /usr/share/gocode/src/, and debian/vendor/ is symlinked as the
vendor/ directory at the go.chromium.org/build/ level, covering both
siso and kajiya.

As of v1.5.13, 4 modules remain in debian/vendor/:

  github.com/bazelbuild/remote-apis (Apache-2.0)
    Remote Execution API protocol buffer definitions. Used by siso's core
    REAPI implementation (30+ source files import this). The upstream
    repository has NO stable Go module releases -- only release-candidate
    tags (v2.3.0-rc2 through v2.9.0-rc1) and a date-based tag (v20250211).
    siso pins to a commit hash (v0.0.0-20260331...). Not independently
    useful outside Bazel/Chromium remote execution infrastructure.

  github.com/bazelbuild/remote-apis-sdks (Apache-2.0)
    Go client SDK for the Remote Execution API. The upstream repository has
    ZERO tags -- no releases whatsoever. siso pins to a commit hash
    (v0.0.0-20260407...). Tightly coupled to remote-apis above.

  github.com/bazelbuild/reclient/api (Apache-2.0)
    Protocol buffer definitions for Google's reclient (remote compilation
    client). The upstream repository has no Go module releases -- siso pins
    to a commit hash (v0.0.0-20240617...). Only contains proto-generated
    .pb.go files. Not useful outside Google's build infrastructure.

  github.com/GoogleCloudPlatform/protoc-gen-bq-schema/protos (Apache-2.0)
    Proto annotations for BigQuery schema generation. Only the protos/
    subdirectory is needed, as a blank import (_) in reclient/api's
    generated proto code. Transitively required by reclient/api -- cannot
    be removed without also removing reclient. While the upstream project
    has stable releases (v1.1.0), packaging just the protos/ subdirectory
    as a standalone Debian package would be unusual. Not packaged in Debian
    and has no reverse-dependencies in Debian besides siso.

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 89 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 (84 modules).

  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.

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

The test suite is run with `go test -short` excluding packages that require:

  - Network access (auth, fetch, proxy)
  - Remote Build Execution infrastructure (e2etests, reapitest, reproxyexec)
  - Google Cloud services (resultstore, trace)
  - python3 (runtimex -- not in minimal build chroot)

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
