Documentation on build flags is gone

[abitrolly]

Checklist

• Are you running the latest v3 release? The list of releases is here.
• Did you check the manual for your release? The v3 manual is here.
• Did you perform a search about this feature? Here's the GitHub guide about searching.

What problem does this solve?

v1 and v2 had build flags to turn off unneeded features and reduce binary sizes.

• Add urfave_cli_no_docs build tag #1375
• Add usage example for urfave_cli_no_docs flag #1604
• v2: Add build tag urfave_cli_no_suggest #1847

But the web site - https://cli.urfave.org/ - is silent about them, and migration guide also doesn't mention they were removed.

Solution description

Document what happened to the build options. Are they gone? Can they be implemented again? Is it only documentation that is missing?

[kolyshkin]

It looks like urfave_cli_no_docs is no longer needed as the functionality lives in a separate package, urfave/cli-docs.

FWIW I don't see any go:build tags in cli v3 or any of its dependencies. It probably relies on DCO (dead code elimination) but it doesn't always work (because of reflect use etc.), so I it would be nice to have some build tags to reduce functionality (and code size).

For example, we can have

• urfave_cli_no_completion to disable shell completion support
• urfave_cli_minimal to disable all optional features
  etc.

Of course, only if it helps to reduce the code size.

Yet better would be to move this into separate packages, like it was done with cli-docs.

[abitrolly]

Automatic dead code elimination works better with external packages? https://cli.urfave.org/v3/examples/completions/shell-completions/ says the completion is enabled by setting EnableShellCompletion: true. If DCO is not smart enough to detect the dead branch with false, what will change if the completion is moved to the separate package?

[kolyshkin]

If DCO is not smart enough to detect the dead branch with false

Usually it is smart, but when you use some reflection features (maybe indirectly via text/template or other dependency, for runc I think it's github.com/godbus/dbus) for introspecting the program, essentially meaning that every function/method/etc in your program is reachable (via reflection). Meaning, DCO does not know whether removing something will result in breakage or not.

I don't know much details about it, you can check e.g. https://github.com/aarzilli/whydeadcode (presentation etc).

what will change if the completion is moved to the separate package?

Everything. Moving to a separate package (in a right way) means you need to explicitly import those packages in order to get the provided functionality, making it opt-in and not even reachable by default. This is usually achieved via init() functions and/or some explicit assignments.

Here's a quick and dirty example:

1. Main package contains these:

package cli

var (
   func ShellCompleteThis(context.Context, *Command) error
   func ShellCompleteOther(c *Command, arguments []string) (bool, []string) 
)

Those are nil by default, so before calling those users should check for nil:

if ShellCompleteThis != nil {
  // Completion functionality is available.
  ...
  err := ShellCompleteThis(c, cmd)
  ...
}

2. Now, the separate package, github.com/urfave/cli/v3/completion, has this:

// Package completion implements shell completion functionality for urfave/cli.
pkg completion

import (
       cli "github.com/urfave/cli/v3"
)

func init() {
   cli.ShellCompleteThis = myShellCompleteThis
   cli.ShellCompleteThat = myShellCompleteThat
}

3. Finally, user's program that wants shell completion from urfave/cli needs to

package myapp

import (
   "github.com/urfave/cli/v3"
   // Comment out the next like to disable shell completion.
   _ "github.com/urfave/cli/v3/completion"
)

That's how I see it. This is easier to use than build tags but is opt-in (and probably can't be made opt-out).

Now, if your app wants a build tag to enable or disable this:

//go:build with_completion // or !without_completion
package myapp

import _ ""github.com/urfave/cli/v3/completion"

All this is untested as I just typed it here, but a similar solution is used by e.g. github.com/opencontainers/cgroups to enable device filters functionality for cgroups (which brings in lots of dependencies and is not always needed).

[abitrolly]

3. Now, the separate package, github.com/urfave/cli/v3/completion, has this:

// Package completion implements shell completion functionality for urfave/cli.
pkg completion

import (
cli "github.com/urfave/cli/v3"
)

func init() {
cli.ShellCompleteThis = myShellCompleteThis
cli.ShellCompleteThat = myShellCompleteThat
}

Monkeypatching module from another module looks an awful anti-pattern. I imagine myself ripping hairs off trying to troubleshoot this without knowing the code. Where the code in github.com/opencontainers/cgroups does this?

[kolyshkin]

Monkeypatching module from another module looks an awful anti-pattern.
I imagine myself ripping hairs off trying to troubleshoot this without knowing the code.

As awful as it may be, that's the only way I found. Eager to learn a better approach if it exists.

Where the code in github.com/opencontainers/cgroups does this?

github.com/opencontainers/cgroups/devices is such a package (see its init() here).

If explicitly imported, it allows github.com/opencontainers/cgroups to manage device access (which, in case of cgroup v2, requires a bunch of dependencies like github.com/cilium/ebpf and not all cgroups users want that.

An example of a user that wants cgroup device access management is runc (here).

Examples of apps that don't want cgroup device access management from oc/cgroups are podman, kubernetes, etc.

[abitrolly]

@kolyshkin I wonder what would be an official take on that in Go discussions? Some "import patches Xxx, Yyyy from zzzz" syntax? How Rust handles this? Python obviously doesn't do any DCO, and I am coming from Python.