diff --git a/main.go b/main.go index e4c0c2b1f0..0d3424fe76 100644 --- a/main.go +++ b/main.go @@ -1257,120 +1257,138 @@ func getBMPPorts() (gdbPort, uartPort string, err error) { } const ( - usageBuild = ` Compile the given program. The output binary is specified using the -o parameter. -The generated file type depends on the extension: + 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. + .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. + .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. + .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. + .hex: + Create an Intel HEX file to flash it to a microcontroller. - .bin - Similar, but create a binary file. + .bin: + Similar, but create a binary file. - .wasm - Compile and link a WebAssembly 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.` +(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).\` + 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". + 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. + 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. + 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 = `Compile 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.` + 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.` + 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 [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` + 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 (