cmd/gomobile: generate package documentation
Change-Id: I2a41cf0f16dcefe87c73ab0a8f02a251c1243157
Reviewed-on: https://go-review.googlesource.com/8121
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
diff --git a/cmd/gomobile/bind.go b/cmd/gomobile/bind.go
index cb06a8b..899857d 100644
--- a/cmd/gomobile/bind.go
+++ b/cmd/gomobile/bind.go
@@ -31,7 +31,7 @@
run: runBind,
Name: "bind",
Usage: "[package]",
- Short: "build a shared library for android APK and/or iOS app",
+ Short: "build a shared library for android APK and iOS app",
Long: `
Bind generates language bindings like gobind (golang.org/x/mobile/cmd/gobind)
for a package and builds a shared library for each platform from the go binding
diff --git a/cmd/gomobile/build.go b/cmd/gomobile/build.go
index aa0bdd2..fbb30f1 100644
--- a/cmd/gomobile/build.go
+++ b/cmd/gomobile/build.go
@@ -29,8 +29,8 @@
var cmdBuild = &command{
run: runBuild,
Name: "build",
- Usage: "[package]",
- Short: "compile android APK and/or iOS app",
+ Usage: "[-o output] [-i] [build flags] [package]",
+ Short: "compile android APK and iOS app",
Long: `
Build compiles and encodes the app named by the import path.
diff --git a/cmd/gomobile/doc.go b/cmd/gomobile/doc.go
new file mode 100644
index 0000000..ffb8091
--- /dev/null
+++ b/cmd/gomobile/doc.go
@@ -0,0 +1,134 @@
+// Copyright 2015 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// DO NOT EDIT. GENERATED BY 'gomobile help documentation'.
+
+/*
+Gomobile is a tool for building and running mobile apps written in Go.
+
+Installation:
+
+ $ go get golang.org/x/mobile/cmd/gomobile
+ $ gomobile init
+
+ Note that until Go 1.5 is released, you must compile Go from
+ tip. For details see https://golang.org/doc/install/source.
+ The minimum process is:
+
+ $ git clone https://go.googlesource.com/go
+ $ cd go/src
+ $ ./all.bash
+
+Usage:
+
+ gomobile command [arguments]
+
+Commands:
+
+ bind build a shared library for android APK and iOS app
+ build compile android APK and iOS app
+ init install android compiler toolchain
+ install compile android APK and iOS app and install on device
+
+Use 'gomobile help [command]' for more information about that command.
+
+NOTE: iOS support is not ready yet.
+
+
+Build a shared library for android APK and iOS app
+
+Usage:
+
+ gomobile bind [package]
+
+Bind generates language bindings like gobind (golang.org/x/mobile/cmd/gobind)
+for a package and builds a shared library for each platform from the go binding
+code.
+
+The -outdir flag specifies the output directory and is required.
+
+For Android, the bind command will place the generated Java API stubs and the
+compiled shared libraries in the android subdirectory of the following layout.
+
+<outdir>/android
+ libs/
+ armeabi-v7a/libgojni.so
+ ...
+ src/main/java/go/
+ Seq.java
+ Go.java
+ mypackage/Mypackage.java
+
+The -v flag provides verbose output, including the list of packages built.
+
+These build flags are shared by the build command.
+For documentation, see 'go help build':
+ -a
+ -i
+ -n
+ -x
+ -tags 'tag list'
+
+
+Compile android APK and iOS app
+
+Usage:
+
+ gomobile build [-o output] [-i] [build flags] [package]
+
+Build compiles and encodes the app named by the import path.
+
+The named package must define a main function.
+
+If an AndroidManifest.xml is defined in the package directory, it is
+added to the APK file. Otherwise, a default manifest is generated.
+
+If the package directory contains an assets subdirectory, its contents
+are copied into the APK file.
+
+The -o flag specifies the output file name. If not specified, the
+output file name depends on the package built. The output file must end
+in '.apk'.
+
+The -v flag provides verbose output, including the list of packages built.
+
+These build flags are shared by the build, install, and test commands.
+For documentation, see 'go help build':
+ -a
+ -i
+ -n
+ -x
+ -tags 'tag list'
+
+
+Install android compiler toolchain
+
+Usage:
+
+ gomobile init [-u]
+
+Init downloads and installs the Android C++ compiler toolchain.
+
+The toolchain is installed in $GOPATH/pkg/gomobile.
+If the Android C++ compiler toolchain already exists in the path,
+it skips download and uses the existing toolchain.
+
+The -u option forces download and installation of the new toolchain
+even when the toolchain exists.
+
+
+Compile android APK and iOS app and install on device
+
+Usage:
+
+ gomobile install [package]
+
+Install compiles and installs the app named by the import path on the
+attached mobile device.
+
+This command requires the 'adb' tool on the PATH.
+
+See the build command help for common flags and common behavior.
+*/
+package main
diff --git a/cmd/gomobile/init.go b/cmd/gomobile/init.go
index c691e51..8401e01 100644
--- a/cmd/gomobile/init.go
+++ b/cmd/gomobile/init.go
@@ -49,6 +49,7 @@
var cmdInit = &command{
run: runInit,
Name: "init",
+ Usage: "[-u]",
Short: "install android compiler toolchain",
Long: `
Init downloads and installs the Android C++ compiler toolchain.
diff --git a/cmd/gomobile/install.go b/cmd/gomobile/install.go
index 615a07a..94511ec 100644
--- a/cmd/gomobile/install.go
+++ b/cmd/gomobile/install.go
@@ -14,7 +14,7 @@
run: runInstall,
Name: "install",
Usage: "[package]",
- Short: "compile android APK and/or iOS app and install on device",
+ Short: "compile android APK and iOS app and install on device",
Long: `
Install compiles and installs the app named by the import path on the
attached mobile device.
diff --git a/cmd/gomobile/main.go b/cmd/gomobile/main.go
index b091c90..145edb8 100644
--- a/cmd/gomobile/main.go
+++ b/cmd/gomobile/main.go
@@ -2,21 +2,22 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-/*
-Gomobile is a tool for building and running mobile apps written in Go.
-
-The tool is under development and not ready for use.
-*/
package main
+//go:generate gomobile help documentation doc.go
+
import (
"bufio"
+ "bytes"
"flag"
"fmt"
"html/template"
"io"
+ "io/ioutil"
"log"
"os"
+ "unicode"
+ "unicode/utf8"
)
func printUsage(w io.Writer) {
@@ -44,6 +45,10 @@
}
if args[0] == "help" {
+ if len(args) == 3 && args[1] == "documentation" {
+ helpDocumentation(args[2])
+ return
+ }
help(args[1:])
return
}
@@ -91,6 +96,37 @@
os.Exit(2)
}
+const documentationHeader = `// Copyright 2015 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// DO NOT EDIT. GENERATED BY 'gomobile help documentation'.
+`
+
+func helpDocumentation(path string) {
+ w := new(bytes.Buffer)
+ w.WriteString(documentationHeader)
+ w.WriteString("\n/*\n")
+ if err := usageTmpl.Execute(w, commands); err != nil {
+ log.Fatal(err)
+ }
+
+ for _, cmd := range commands {
+ r, rlen := utf8.DecodeRuneInString(cmd.Short)
+ w.WriteString("\n\n")
+ w.WriteRune(unicode.ToUpper(r))
+ w.WriteString(cmd.Short[rlen:])
+ w.WriteString("\n\nUsage:\n\n\tgomobile " + cmd.Name + " " + cmd.Usage + "\n")
+ w.WriteString(cmd.Long)
+ }
+
+ w.WriteString("*/\npackage main\n")
+
+ if err := ioutil.WriteFile(path, w.Bytes(), 0666); err != nil {
+ log.Fatal(err)
+ }
+}
+
var commands = []*command{
// TODO(crawshaw): cmdRun
cmdBind,
@@ -113,7 +149,20 @@
}
var usageTmpl = template.Must(template.New("usage").Parse(
- `Gomobile is a tool for building Android and iOS Go apps.
+ `Gomobile is a tool for building and running mobile apps written in Go.
+
+Installation:
+
+ $ go get golang.org/x/mobile/cmd/gomobile
+ $ gomobile init
+
+ Note that until Go 1.5 is released, you must compile Go from
+ tip. For details see https://golang.org/doc/install/source.
+ The minimum process is:
+
+ $ git clone https://go.googlesource.com/go
+ $ cd go/src
+ $ ./all.bash
Usage:
@@ -124,4 +173,6 @@
{{.Name | printf "%-11s"}} {{.Short}}{{end}}
Use 'gomobile help [command]' for more information about that command.
+
+NOTE: iOS support is not ready yet.
`))
