github.com/cockroachdb/tools@v0.0.0-20230222021103-a6d27438930d/cmd/godex/doc.go (about)

     1  // Copyright 2014 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // The godex command prints (dumps) exported information of packages
     6  // or selected package objects.
     7  //
     8  // In contrast to godoc, godex extracts this information from compiled
     9  // object files. Hence the exported data is truly what a compiler will
    10  // see, at the cost of missing commentary.
    11  //
    12  // Usage: godex [flags] {path[.name]}
    13  //
    14  // Each argument must be a (possibly partial) package path, optionally
    15  // followed by a dot and the name of a package object:
    16  //
    17  //	godex math
    18  //	godex math.Sin
    19  //	godex math.Sin fmt.Printf
    20  //	godex go/types
    21  //
    22  // godex automatically tries all possible package path prefixes if only a
    23  // partial package path is given. For instance, for the path "go/types",
    24  // godex prepends "golang.org/x/tools".
    25  //
    26  // The prefixes are computed by searching the directories specified by
    27  // the GOROOT and GOPATH environment variables (and by excluding the
    28  // build OS- and architecture-specific directory names from the path).
    29  // The search order is depth-first and alphabetic; for a partial path
    30  // "foo", a package "a/foo" is found before "b/foo".
    31  //
    32  // Absolute and relative paths may be provided, which disable automatic
    33  // prefix generation:
    34  //
    35  //	godex $GOROOT/pkg/darwin_amd64/sort
    36  //	godex ./sort
    37  //
    38  // All but the last path element may contain dots; a dot in the last path
    39  // element separates the package path from the package object name. If the
    40  // last path element contains a dot, terminate the argument with another
    41  // dot (indicating an empty object name). For instance, the path for a
    42  // package foo.bar would be specified as in:
    43  //
    44  //	godex foo.bar.
    45  //
    46  // The flags are:
    47  //
    48  //	-s=""
    49  //		only consider packages from src, where src is one of the supported compilers
    50  //	-v=false
    51  //		verbose mode
    52  //
    53  // The following sources (-s arguments) are supported:
    54  //
    55  //	gc
    56  //		gc-generated object files
    57  //	gccgo
    58  //		gccgo-generated object files
    59  //	gccgo-new
    60  //		gccgo-generated object files using a condensed format (experimental)
    61  //	source
    62  //		(uncompiled) source code (not yet implemented)
    63  //
    64  // If no -s argument is provided, godex will try to find a matching source.
    65  package main // import "golang.org/x/tools/cmd/godex"
    66  
    67  // BUG(gri): support for -s=source is not yet implemented
    68  // BUG(gri): gccgo-importing appears to have occasional problems stalling godex; try -s=gc as work-around