Remove gndoc This has moved into fuchsia.git //tools/build/gndoc now. Change-Id: Ie14eb8b1fa1ad2e3b53836db1178981afb506b26 Reviewed-on: https://fuchsia-review.googlesource.com/c/tools/+/1489336 Reviewed-by: Petr Hosek <phosek@google.com> Fuchsia-Auto-Submit: Roland McGrath <mcgrathr@google.com>
diff --git a/gndoc/argmap.go b/gndoc/argmap.go deleted file mode 100644 index eae9cf5..0000000 --- a/gndoc/argmap.go +++ /dev/null
@@ -1,98 +0,0 @@ -// Copyright 2018 The Fuchsia Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -package gndoc - -import ( - "fmt" - "io" - "sort" - "strings" -) - -type ArgMap struct { - argLookup map[string][]string // map of arg names to keys for lookup - args map[string][]Arg // map of key names to relevant args -} - -// NewArgMap returns a pointer to an -func NewArgMap() *ArgMap { - return &ArgMap{ - argLookup: make(map[string][]string), - args: make(map[string][]Arg), - } -} - -// AddArgs creates args from GNArgs and adds them to the maps -func (a *ArgMap) AddArgs(gnArgs <-chan Arg) { - for gnArg := range gnArgs { - a.AddArg(gnArg) - } -} - -// AddArg adds Arg to the maps -func (a *ArgMap) AddArg(gnArg Arg) { - a.args[gnArg.Key] = append(a.args[gnArg.Key], gnArg) - a.argLookup[gnArg.Name] = append(a.argLookup[gnArg.Name], gnArg.Key) -} - -// EmitMarkdown emits Markdown text for the map of arguments. -func (a *ArgMap) EmitMarkdown(out io.Writer) { - type mappedArgs struct { - m map[string][]Arg - k []string - } - sortedArgs := struct { - m map[string]*mappedArgs - k []string - }{ - m: make(map[string]*mappedArgs), - k: make([]string, 0), - } - - numKeys := len(a.args) - for _, gnArgs := range a.args { - for _, gnArg := range gnArgs { - // Lookup the keys associated with this arg & sort & stringify. - keys, _ := a.argLookup[gnArg.Name] - if len(keys) == numKeys { - // Incoming keys will always have an `=`, and so this is an - // okay value. - keys = []string{"all"} - } - sort.Strings(keys) - key := strings.Join(keys, ", ") - if _, ok := sortedArgs.m[key]; !ok { - sortedArgs.m[key] = &mappedArgs{ - m: make(map[string][]Arg), - k: make([]string, 0)} - } - sortedArgs.m[key].m[gnArg.Name] = append(sortedArgs.m[key].m[gnArg.Name], gnArg) - } - } - for k := range sortedArgs.m { - for argName := range sortedArgs.m[k].m { - sort.Slice(sortedArgs.m[k].m[argName], func(i, j int) bool { - return sortedArgs.m[k].m[argName][i].Key < sortedArgs.m[k].m[argName][j].Key - }) - sortedArgs.m[k].k = append(sortedArgs.m[k].k, argName) - } - sort.Strings(sortedArgs.m[k].k) - sortedArgs.k = append(sortedArgs.k, k) - } - sort.Strings(sortedArgs.k) - // Emit a header. - fmt.Fprintf(out, "# %s\n\n", pageTitle) - for _, name := range sortedArgs.k { - if name == "all" { - fmt.Fprintf(out, "## All builds\n\n") - } else { - fmt.Fprintf(out, "## `%s`\n\n", name) - } - for _, argsKey := range sortedArgs.m[name].k { - gnArgs := sortedArgs.m[name].m[argsKey] - writeArgs(gnArgs, out) - } - } -}
diff --git a/gndoc/argmap_test.go b/gndoc/argmap_test.go deleted file mode 100644 index 7c16ada..0000000 --- a/gndoc/argmap_test.go +++ /dev/null
@@ -1,143 +0,0 @@ -// Copyright 2019 The Fuchsia Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -package gndoc - -import ( - "bytes" - "math/rand" - "testing" - "time" -) - -func genArgMapInRandomOrder() *ArgMap { - testArgMap := NewArgMap() - gnArgs := []Arg{ - defaultx64Arg, - defaultarm64Arg, - defaultarm64ArgWithCurrent, - defaultx64ArgWithCurrent, - x64Arg, - arm64Arg, - twoKeyarm64TestArg, - twoKeyx64TestArg, - twoKeyarm64OtherArg, - twoKeyx64OtherArg, - newLineValueArg, - } - // Shuffle the gnArgs. - r := rand.New(rand.NewSource(time.Now().Unix())) - shuffledGnArgs := make([]Arg, 0) - for _, j := range r.Perm(len(gnArgs)) { - shuffledGnArgs = append(shuffledGnArgs, gnArgs[j]) - } - for _, arg := range shuffledGnArgs { - testArgMap.AddArg(arg) - } - return testArgMap -} - -func TestArgMapEmitMarkdown(t *testing.T) { - expectedOutput := `# GN Build Arguments - -## ` + "`target_cpu = arm64, package='other/package/default'`" + ` - -### arm64Other - -Description of arm64 arg. - -**Current value for ` + "`target_cpu = arm64, package='other/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -## ` + "`target_cpu = arm64, target_cpu = arm64, package='test/package/default'`" + ` - -### arm64 - -Description of arm64 arg. - -**Current value for ` + "`target_cpu = arm64`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -**Current value for ` + "`target_cpu = arm64, package='test/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -## ` + "`target_cpu = arm64, target_cpu = x64`" + ` - -### default - -Description of default arg. - -**Current value (from the default):** ` + "`false`" + ` - -From //test/BUILD.gn:2 - -### default_current - -Description of default_current arg. - -**Current value for ` + "`target_cpu = arm64`:** `[1, 2]`" + ` - -From //build/BUILD.gn:24 - -**Overridden from the default:** ` + "`[3, 4]`" + ` - -From //base/BUILD.gn:4 - -**Current value for ` + "`target_cpu = x64`:** `3`" + ` - -From //build/BUILD.gn:24 - -**Overridden from the default:** ` + "`4`" + ` - -From //base/BUILD.gn:2 - -## ` + "`target_cpu = x64, package='other/package/default'`" + ` - -### NewLine - -Description of newline arg. - -**Current value (from the default):** -` + "\n```none" + ` -{ - base = "//build/toolchain/fuchsia:x64" -} -` + "```" + ` - -### x64Other - -Description of x64 arg. - -**Current value for ` + "`target_cpu = x64, package='other/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -## ` + "`target_cpu = x64, target_cpu = x64, package='test/package/default'`" + ` - -### x64 - -Description of x64 arg that references //build/path.py, //sources, and //base. - -**Current value for ` + "`target_cpu = x64`:** `1`" + ` - -**Overridden from the default:** ` + "`2`" + ` - -**Current value for ` + "`target_cpu = x64, package='test/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -` - for i := 0; i < 10; i++ { - testArgMap := genArgMapInRandomOrder() - var testOutput bytes.Buffer - testArgMap.EmitMarkdown(&testOutput) - if expectedOutput != testOutput.String() { - t.Errorf("expecting output:\n%s\n, got:\n%s\n", expectedOutput, testOutput.String()) - break - } - } -}
diff --git a/gndoc/argparser.go b/gndoc/argparser.go deleted file mode 100644 index a21ad0e..0000000 --- a/gndoc/argparser.go +++ /dev/null
@@ -1,93 +0,0 @@ -// Copyright 2018 The Fuchsia Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -package gndoc - -import ( - "context" - "encoding/json" - "fmt" - "os" - "strings" -) - -// Arg holds the information directly parsed from the json output of `gn args <build> --list --json`. -type Arg struct { - Name string `json:"name"` - CurrentVal argValue `json:"current"` - DefaultVal argValue `json:"default"` - Comment string `json:"comment"` - Key string `json: "-"` -} - -// ArgValue holds a value, its filepath and line number, and the build associated with the value. -type argValue struct { - Val string `json:"value"` - File string `json:"file"` - Line int `json:"line"` -} - -// ParseGNArgs runs the necessary gn commands and decodes the json output into a channel of GNArgs. -func ParseGNArgs(ctx context.Context, inputFiles []string, keyArgs []string) (<-chan Arg, <-chan error) { - args := make(chan Arg) - errs := make(chan error, 1) - go func() { - defer func() { - close(args) - close(errs) - }() - for _, input := range inputFiles { - select { - case <-ctx.Done(): - return - default: - err := parseJson(input, keyArgs, args) - if err != nil { - errs <- err - return - } - } - } - }() - return args, errs -} - -func parseJson(input string, keyArgs []string, out chan<- Arg) error { - // Open the json file. - file, err := os.Open(input) - if err != nil { - return err - } - defer file.Close() - - // Decode the json into GNArgs. - var gnArgs []Arg - decoder := json.NewDecoder(file) - if err := decoder.Decode(&gnArgs); err != nil { - return err - } - - // Mark the args with the relevant key and send to channel. - key := getKey(gnArgs, keyArgs) - for _, arg := range gnArgs { - arg.Key = key - out <- arg - } - - return nil -} - -// TODO: make sure this is sorted before stringifying -// getKey searches the decoded json for the flagged keys and builds the marker string. -func getKey(args []Arg, keys []string) string { - keyVals := make([]string, len(keys)) - for _, arg := range args { - for idx, key := range keys { - if arg.Name == key { - keyVals[idx] = fmt.Sprintf("%s = %v", key, arg.CurrentVal.Val) - } - } - } - return strings.Join(keyVals, ", ") -}
diff --git a/gndoc/cmd/main.go b/gndoc/cmd/main.go deleted file mode 100644 index 0e500e8..0000000 --- a/gndoc/cmd/main.go +++ /dev/null
@@ -1,73 +0,0 @@ -// Copyright 2018 The Fuchsia Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -package main - -import ( - "context" - "flag" - "io" - "log" - "os" - "path/filepath" - "strings" - - "go.fuchsia.dev/tools/gndoc" -) - -type stringsFlag []string - -func (s *stringsFlag) String() string { - return strings.Join(*s, ", ") -} - -func (s *stringsFlag) Set(value string) error { - *s = append(*s, value) - return nil -} - -var ( - keyArgs stringsFlag - inputFiles stringsFlag - outFile string - sourcesFile string -) - -func init() { - flag.Var(&keyArgs, "key", "a label for output") - flag.Var(&inputFiles, "in", "path to an input file") - flag.StringVar(&outFile, "out", "", "path to output file (default stdout)") -} - -func main() { - flag.Parse() - if flag.NArg() != 0 { - flag.PrintDefaults() - } - - ctx := context.Background() - argMap := gndoc.NewArgMap() - - args, errs := gndoc.ParseGNArgs(ctx, inputFiles, keyArgs) - argMap.AddArgs(args) - if err := <-errs; err != nil { - log.Fatalf("Error: %s\n", err) - } - - var out io.Writer - if outFile != "" { - var err error - if dirErr := os.MkdirAll(filepath.Dir(outFile), os.ModePerm); dirErr != nil { - log.Fatalf("Error creating directories: %s", dirErr) - } - out, err = os.Create(outFile) - if err != nil { - log.Fatalf("Error opening file: %s", err) - } - } else { - out = os.Stdout - } - - argMap.EmitMarkdown(out) -}
diff --git a/gndoc/formatter.go b/gndoc/formatter.go deleted file mode 100644 index 3e92edc..0000000 --- a/gndoc/formatter.go +++ /dev/null
@@ -1,76 +0,0 @@ -// Copyright 2018 The Fuchsia Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -package gndoc - -import ( - "fmt" - "io" - "regexp" - "sort" - "strings" -) - -const ( - pageTitle = "GN Build Arguments" - nameDepth = 3 -) - -var ( - linkRegexp = regexp.MustCompile("//([/A-Za-z-_]+)([.][/A-Za-z-_]+)?") -) - -// writeArg emits the name, comment description, and value(s) of the argument in Markdown. -func writeArgs(args []Arg, out io.Writer) { - if len(args) == 0 { - return - } - sort.Slice(args, func(i, j int) bool { - return args[i].Name < args[j].Name - }) - - // Include a blank line after heading for properly formatted markdown. - fmt.Fprintf(out, "%s %s\n\n", strings.Repeat("#", nameDepth), args[0].Name) - // TODO (juliehockett): Make sure that *all* comments get emitted. - writeLinkifiedComment(&args[0], out) - writeAllValues(args, out) -} - -// writeValue emits the value of a given argument value, along with the associated Markdown link to its declaration and build (if present). -func writeValue(a *argValue, out io.Writer) { - var value string - if strings.Contains(a.Val, "\n") { - value = fmt.Sprintf("\n\n```none\n%s\n```", a.Val) - } else { - value = fmt.Sprintf(" `%s`", a.Val) - } - - if a.File == "" { - // If there is no declaration file, emit just the value. - fmt.Fprintf(out, "%s\n\n", value) - } else { - fmt.Fprintf(out, "%s\n\nFrom %s:%d\n\n", value, a.File, a.Line) - } -} - -func writeLinkifiedComment(a *Arg, out io.Writer) { - if a.Comment != "" { - fmt.Fprintf(out, "%s\n", a.Comment) - } -} - -func writeAllValues(args []Arg, out io.Writer) { - emptyArgValue := argValue{} - for _, a := range args { - if a.CurrentVal == emptyArgValue || a.CurrentVal == a.DefaultVal { - fmt.Fprintf(out, "**Current value (from the default):**") - writeValue(&a.DefaultVal, out) - return - } - fmt.Fprintf(out, "**Current value for `%s`:**", a.Key) - writeValue(&a.CurrentVal, out) - fmt.Fprintf(out, "**Overridden from the default:**") - writeValue(&a.DefaultVal, out) - } -}
diff --git a/gndoc/formatter_test.go b/gndoc/formatter_test.go deleted file mode 100644 index 999026f..0000000 --- a/gndoc/formatter_test.go +++ /dev/null
@@ -1,362 +0,0 @@ -// Copyright 2018 The Fuchsia Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -package gndoc - -import ( - "bytes" - "testing" -) - -const ( - numKeys = 2 -) - -var ( - defaultx64Arg = Arg{ - Name: "default", - DefaultVal: argValue{ - Val: "false", - File: "//test/BUILD.gn", - Line: 2, - }, - Comment: "Description of default arg.\n", - Key: "target_cpu = x64", - } - - defaultarm64Arg = Arg{ - Name: "default", - DefaultVal: argValue{ - Val: "false", - File: "//test/BUILD.gn", - Line: 2, - }, - Comment: "Description of default arg.\n", - Key: "target_cpu = arm64", - } - - defaultarm64ArgWithCurrent = Arg{ - Name: "default_current", - CurrentVal: argValue{ - Val: "[1, 2]", - File: "//build/BUILD.gn", - Line: 24, - }, - DefaultVal: argValue{ - Val: "[3, 4]", - File: "//base/BUILD.gn", - Line: 4, - }, - Comment: "Description of default_current arg.\n", - Key: "target_cpu = arm64", - } - - defaultx64ArgWithCurrent = Arg{ - Name: "default_current", - CurrentVal: argValue{ - Val: "3", - File: "//build/BUILD.gn", - Line: 24, - }, - DefaultVal: argValue{ - Val: "4", - File: "//base/BUILD.gn", - Line: 2, - }, - Comment: "Description of default_current arg.\n", - Key: "target_cpu = x64", - } - - x64Arg = Arg{ - Name: "x64", - CurrentVal: argValue{ - Val: "1", - }, - DefaultVal: argValue{ - Val: "2", - }, - Comment: "Description of x64 arg that references //build/path.py, //sources, and //base.\n", - Key: "target_cpu = x64", - } - - arm64Arg = Arg{ - Name: "arm64", - CurrentVal: argValue{ - Val: "arg", - }, - DefaultVal: argValue{ - Val: "value", - }, - Comment: "Description of arm64 arg.\n", - Key: "target_cpu = arm64", - } - - twoKeyarm64TestArg = Arg{ - Name: "arm64", - CurrentVal: argValue{ - Val: "arg", - }, - DefaultVal: argValue{ - Val: "value", - }, - Comment: "Description of arm64 arg.\n", - Key: "target_cpu = arm64, package='test/package/default'", - } - - twoKeyx64TestArg = Arg{ - Name: "x64", - CurrentVal: argValue{ - Val: "arg", - }, - DefaultVal: argValue{ - Val: "value", - }, - Comment: "Description of x64 arg.\n", - Key: "target_cpu = x64, package='test/package/default'", - } - - twoKeyarm64OtherArg = Arg{ - Name: "arm64Other", - CurrentVal: argValue{ - Val: "arg", - }, - DefaultVal: argValue{ - Val: "value", - }, - Comment: "Description of arm64 arg.\n", - Key: "target_cpu = arm64, package='other/package/default'", - } - - twoKeyx64OtherArg = Arg{ - Name: "x64Other", - CurrentVal: argValue{ - Val: "arg", - }, - DefaultVal: argValue{ - Val: "value", - }, - Comment: "Description of x64 arg.\n", - Key: "target_cpu = x64, package='other/package/default'", - } - - newLineValueArg = Arg{ - Name: "NewLine", - DefaultVal: argValue{ - Val: "{\n base = \"//build/toolchain/fuchsia:x64\"\n}", - }, - Comment: "Description of newline arg.\n", - Key: "target_cpu = x64, package='other/package/default'", - } -) - -func TestDefault(t *testing.T) { - - gnArgs := []Arg{defaultx64Arg, defaultarm64Arg} - argMap := NewArgMap() - for _, arg := range gnArgs { - argMap.AddArg(arg) - } - - // No file name emits to stdout. - var buffer bytes.Buffer - argMap.EmitMarkdown(&buffer) - - actual := buffer.String() - expected := `# GN Build Arguments - -## All builds - -### default - -Description of default arg. - -**Current value (from the default):** ` + "`false`" + ` - -From //test/BUILD.gn:2 - -` - if expected != actual { - t.Fatalf("In TestDefault, expected \n%s but got \n%s", expected, actual) - } -} - -func TestDefaultWithCurrent(t *testing.T) { - - gnArgs := []Arg{defaultx64ArgWithCurrent, defaultarm64ArgWithCurrent} - argMap := NewArgMap() - for _, arg := range gnArgs { - argMap.AddArg(arg) - } - - // No file name emits to stdout. - var buffer bytes.Buffer - argMap.EmitMarkdown(&buffer) - - actual := buffer.String() - expected := `# GN Build Arguments - -## All builds - -### default_current - -Description of default_current arg. - -**Current value for ` + "`target_cpu = arm64`:** `[1, 2]`" + ` - -From //build/BUILD.gn:24 - -**Overridden from the default:** ` + "`[3, 4]`" + ` - -From //base/BUILD.gn:4 - -**Current value for ` + "`target_cpu = x64`:** `3`" + ` - -From //build/BUILD.gn:24 - -**Overridden from the default:**` + " `4`" + ` - -From //base/BUILD.gn:2 - -` - - if expected != actual { - t.Fatalf("In TestDefaultWithCurrent, expected \n%s but got \n%s", expected, actual) - } -} - -func TestUnique(t *testing.T) { - - gnArgs := []Arg{x64Arg, arm64Arg} - argMap := NewArgMap() - for _, arg := range gnArgs { - argMap.AddArg(arg) - } - - // No file name emits to stdout. - var buffer bytes.Buffer - argMap.EmitMarkdown(&buffer) - - actual := buffer.String() - expected := `# GN Build Arguments - -## ` + "`target_cpu = arm64`" + ` - -### arm64 - -Description of arm64 arg. - -**Current value for ` + "`target_cpu = arm64`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -## ` + "`target_cpu = x64`" + ` - -### x64 - -Description of x64 arg that references //build/path.py, //sources, and //base. - -**Current value for ` + "`target_cpu = x64`:** `1`" + ` - -**Overridden from the default:** ` + "`2`" + ` - -` - if expected != actual { - t.Fatalf("In TestUnique, expected \n%s but got \n%s", expected, actual) - } -} - -func TestTwoKeys(t *testing.T) { - - gnArgs := []Arg{twoKeyarm64TestArg, twoKeyx64TestArg, twoKeyarm64OtherArg, twoKeyx64OtherArg} - argMap := NewArgMap() - for _, arg := range gnArgs { - argMap.AddArg(arg) - } - - // No file name emits to stdout. - var buffer bytes.Buffer - argMap.EmitMarkdown(&buffer) - - actual := buffer.String() - expected := `# GN Build Arguments - -## ` + "`target_cpu = arm64, package='other/package/default'`" + ` - -### arm64Other - -Description of arm64 arg. - -**Current value for ` + "`target_cpu = arm64, package='other/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -## ` + "`target_cpu = arm64, package='test/package/default'`" + ` - -### arm64 - -Description of arm64 arg. - -**Current value for ` + "`target_cpu = arm64, package='test/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -## ` + "`target_cpu = x64, package='other/package/default'`" + ` - -### x64Other - -Description of x64 arg. - -**Current value for ` + "`target_cpu = x64, package='other/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -## ` + "`target_cpu = x64, package='test/package/default'`" + ` - -### x64 - -Description of x64 arg. - -**Current value for ` + "`target_cpu = x64, package='test/package/default'`:** `arg`" + ` - -**Overridden from the default:** ` + "`value`" + ` - -` - if expected != actual { - t.Fatalf("In TestUnique, expected \n%s but got \n%s", expected, actual) - } -} - -func TestValueNewLine(t *testing.T) { - - gnArgs := []Arg{newLineValueArg} - argMap := NewArgMap() - for _, arg := range gnArgs { - argMap.AddArg(arg) - } - - // No file name emits to stdout. - var buffer bytes.Buffer - argMap.EmitMarkdown(&buffer) - - actual := buffer.String() - expected := `# GN Build Arguments - -## All builds - -### NewLine - -Description of newline arg. - -**Current value (from the default):** -` + "\n```none" + ` -{ - base = "//build/toolchain/fuchsia:x64" -} -` + "```" + ` - -` - if expected != actual { - t.Fatalf("In TestDefault, expected \n%s but got \n%s", expected, actual) - } -}