github.com/facebookincubator/ttpforge@v1.0.13-0.20240405153150-5ae801628835/docs/foundations/requirements.md (about)

     1  # TTP Requirements Specification
     2  
     3  Suppose that a TTPForge user attempts to run a linux-only TTP on a macOS system.
     4  It is better for them to get an immediate, clear error of the form "this TTP can
     5  only be run on macOS" than for them to receive an obscure error such as "XYZ
     6  command not found" that pops up halfway through the execution of their TTP. The
     7  TTPForge `requirements` section solves this problem. By declaring a
     8  `requirements` section, you can clearly indicate to users of your TTP:
     9  
    10  - With which platforms your TTP is compatible.
    11  - Whether your TTP requires superuser privileges.
    12  
    13  ## Specifying Compatible Platforms
    14  
    15  The example below demonstrates how to tell TTPForge (and your TTP's users) that
    16  your TTP is only compatible with (and should therefore only be run) on certain
    17  platforms:
    18  
    19  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/requirements/os-and-superuser.yaml#L1-L21
    20  
    21  Each entry in the `platforms` list should contain one or both of the following
    22  fields:
    23  
    24  - `os`: the target operating system.
    25  - `arch`: the target architecture.
    26  
    27  Since TTPForge is written in [Go](https://go.dev/), you may specify any valid
    28  `GOOS` or `GOARCH` value for these fields - see
    29  [here](https://go.dev/doc/install/source#environment) for the full list of
    30  allowed values.
    31  
    32  Note that it is quite common to specify entries containing `os` but not `arch` -
    33  this simply means that the TTP is compatible with the specified `os` and that
    34  its implementation is not architecture specific. Conversely, the following entry
    35  indicates that the TTP is compatible with ARM-based macOS systems and x64-based
    36  Windows systems, but not with e.g. legacy intel-based macOS systems:
    37  
    38  ```yml
    39  platforms:
    40    - os: darwin
    41      arch: arm64
    42    - os: windows
    43      arch: amd64
    44  ```
    45  
    46  ### How TTPForge Determines the Current OS/Arch
    47  
    48  TTPForge consults its `runtime.GOOS` and `runtime.GOARCH`
    49  [constants](https://pkg.go.dev/runtime#pkg-constants) to determine the OS and
    50  architecture on which it is currently running. These values are based on the
    51  `GOOS` and `GOARCH` settings with which that particular TTPForge executable was
    52  compiled. **Note that these values may sometimes be misleading** - for instance,
    53  if TTPForge was compiled with `GOARCH=amd64`, it will consider itself to be
    54  running on `amd64` even if it is being run on an `arm64` system using
    55  [Rosetta](https://support.apple.com/en-us/HT211861).
    56  
    57  ## Specifying Required Privileges
    58  
    59  If your TTP requires superuser privileges to run, you should specify
    60  `superuser: true` in your `requirements` section, as demonstrated by the TTP
    61  above. This will ensure that your users get an immediate and unambiguous error
    62  message if they attempt to execute your TTP without the required privileges,
    63  rather than a "Permission Denied..." error midway through TTP execution.