main: rework usage

main.go

@@ -1256,36 +1256,169 @@ func getBMPPorts() (gdbPort, uartPort string, err error) {
 	}
 }
 
-func usage(command string) {
-	switch command {
-	default:
-		fmt.Fprintln(os.Stderr, "TinyGo is a Go compiler for small places.")
-		fmt.Fprintln(os.Stderr, "version:", goenv.Version())
-		fmt.Fprintf(os.Stderr, "usage: %s <command> [arguments]\n", os.Args[0])
-		fmt.Fprintln(os.Stderr, "\ncommands:")
-		fmt.Fprintln(os.Stderr, "  build:   compile packages and dependencies")
-		fmt.Fprintln(os.Stderr, "  run:     compile and run immediately")
-		fmt.Fprintln(os.Stderr, "  test:    test packages")
-		fmt.Fprintln(os.Stderr, "  flash:   compile and flash to the device")
-		fmt.Fprintln(os.Stderr, "  gdb:     run/flash and immediately enter GDB")
-		fmt.Fprintln(os.Stderr, "  lldb:    run/flash and immediately enter LLDB")
-		fmt.Fprintln(os.Stderr, "  monitor: open communication port")
-		fmt.Fprintln(os.Stderr, "  ports:   list available serial ports")
-		fmt.Fprintln(os.Stderr, "  env:     list environment variables used during build")
-		fmt.Fprintln(os.Stderr, "  list:    run go list using the TinyGo root")
-		fmt.Fprintln(os.Stderr, "  clean:   empty cache directory ("+goenv.Get("GOCACHE")+")")
-		fmt.Fprintln(os.Stderr, "  targets: list targets")
-		fmt.Fprintln(os.Stderr, "  info:    show info for specified target")
-		fmt.Fprintln(os.Stderr, "  version: show version")
-		fmt.Fprintln(os.Stderr, "  help:    print this help text")
+const (
+	usageBuild = `Build compiles the packages named by the import paths, along with their
+dependencies, but it does not install the results. The output binary is
+specified using the -o parameter. The generated file type depends on the
+extension:
+
+	.o:
+			Create a relocatable object file. You can use this option if you
+			don't want to use the TinyGo build system or want to do other custom
+			things.
+
+	.ll:
+			Create textual LLVM IR, after optimization. This is mainly useful
+			for debugging.
+
+	.bc:
+			Create LLVM bitcode, after optimization. This may be useful for
+			debugging or for linking into other programs using LTO.
+
+	.hex:
+			Create an Intel HEX file to flash it to a microcontroller.
+
+	.bin:
+			Similar, but create a binary file.
+
+	.wasm:
+			Compile and link a WebAssembly file.
+
+(all other) Compile and link the program into a regular executable. For
+microcontrollers, it is common to use the .elf file extension to indicate a
+linked ELF file is generated. For Linux, it is common to build binaries with no
+extension at all.`
+
+	usageRun = `Run the program, either directly on the host or in an emulated environment 
+(depending on -target).`
+
+	usageFlash = `Flash the program to a microcontroller. Some common flags are described below.
+
+	-target={name}: 
+			Specifies the type of microcontroller that is used. The name of the
+			microcontroller is given on the individual pages for each board type
+			listed under Microcontrollers
+			(https://tinygo.org/docs/reference/microcontrollers/).
+			Examples: "arduino-nano", "d1mini", "xiao".
+
+	-monitor: 
+			Start the serial monitor (see below) immediately after
+			flashing. However, some microcontrollers need a split second
+			or two to configure the serial port after flashing, and
+			using the "-monitor" flag can fail because the serial
+			monitor starts too quickly. In that case, use the "tinygo
+			monitor" command explicitly.`
+
+	usageMonitor = `Start the serial monitor on the serial port that is connected to the
+microcontroller. If there is only a single board attached to the host computer,
+the default values for various options should be sufficient. In other
+situations, particularly if you have multiple microcontrollers attached, some
+parameters may need to be overridden using the following flags:
+
+	-port={port}:
+			If there are multiple microcontroller attached, an error
+			message will display a list of potential serial ports. The
+			appropriate port can be specified by this flag. On Linux,
+			the port will be something like /dev/ttyUSB0 or /dev/ttyACM1.
+			On MacOS, the port will look like /dev/cu.usbserial-1420. On
+			Windows, the port will be something like COM1 or COM31.
+
+	-baudrate={rate}:
+			The default baud rate is 115200. Boards using the AVR
+			processor (e.g. Arduino Nano, Arduino Mega 2560) use 9600
+			instead.
+
+	-target={name}:
+			If you have more than one microcontrollers attached, you can
+			sometimes just specify the target name and let tinygo
+			monitor figure out the port. Sometimes, this does not work
+			and you have to explicitly use the -port flag.
+
+The serial monitor intercepts several control characters for its own use instead of sending them
+to the microcontroller:
+
+	Control-C: terminates the tinygo monitor
+	Control-Z: suspends the tinygo monitor and drops back into shell
+	Control-\: terminates the tinygo monitor with a stack trace
+	Control-S: flow control, suspends output to the console
+	Control-Q: flow control, resumes output to the console
+	Control-@: thrown away by tinygo monitor
+
+Note: If you are using os.Stdin on the microcontroller, you may find that a CR
+character on the host computer (also known as Enter, ^M, or \r) is transmitted
+to the microcontroller without conversion, so os.Stdin returns a \r character
+instead of the expected \n (also known as ^J, NL, or LF) to indicate
+end-of-line. You may be able to get around this problem by hitting Control-J in
+tinygo monitor to transmit the \n end-of-line character.`
+
+	usageGdb = `Build the program, optionally flash it to a microcontroller if it is a remote 
+target, and drop into a GDB shell. From there you can set breakpoints, start the
+program with "run" or "continue" ("run" for a local program, continue for
+on-chip debugging), single-step, show a backtrace, break and resume the program
+with Ctrl-C/"continue", etc. You may need to install extra tools (like openocd
+and arm-none-eabi-gdb) to be able to do this. Also, you may need a dedicated
+debugger to be able to debug certain boards if no debugger is integrated. Some
+boards (like the BBC micro:bit and most professional evaluation boards) have an
+integrated debugger.`
+
+	usageClean = `Clean the cache directory, normally stored in $HOME/.cache/tinygo. This is not
+normally needed.`
+
+	usageHelp    = `Print a short summary of the available commands, plus a list of command flags.`
+	usageVersion = `Print the version of the command and the version of the used $GOROOT.`
+	usageEnv     = `Print a list of environment variables that affect TinyGo (as a shell script).
+If one or more variable names are given as arguments, env prints the value of
+each on a new line.`
+
+	usageDefault = `TinyGo is a Go compiler for small places.
+version: %s
+usage: %s <command> [arguments]
+commands:
+		build:		compile packages and dependencies
+		run:		compile and run immediately
+		test:		test packages
+		flash:		compile and flash to the device
+		gdb:		run/flash and immediately enter GDB
+		lldb:		run/flash and immediately enter LLDB
+		monitor:	open communication port
+		ports:		list available serial ports
+		env:		list environment variables used during build
+		list:		run go list using the TinyGo root
+		clean:		empty cache directory (%s)
+		targets:	list targets
+		info:		show info for specified target
+		version:	show version
+		help:		print this help text`
+)
+
+var (
+	commandHelp = map[string]string{
+		"build":   usageBuild,
+		"run":     usageRun,
+		"flash":   usageFlash,
+		"monitor": usageMonitor,
+		"gdb":     usageGdb,
+		"clean":   usageClean,
+		"help":    usageHelp,
+		"version": usageVersion,
+		"env":     usageEnv,
+	}
+)
 
+func usage(command string) {
+	val, ok := commandHelp[command]
+	if !ok {
+		fmt.Fprintf(os.Stderr, usageDefault, goenv.Version(), os.Args[0], goenv.Get("GOCACHE"))
 		if flag.Parsed() {
 			fmt.Fprintln(os.Stderr, "\nflags:")
 			flag.PrintDefaults()
 		}
 
 		fmt.Fprintln(os.Stderr, "\nfor more details, see https://tinygo.org/docs/reference/usage/")
+	} else {
+		fmt.Fprintln(os.Stderr, val)
 	}
+
 }
 
 func handleCompilerError(err error) {