Go Tool: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(48 intermediate revisions by the same user not shown)
Line 16: Line 16:
go help build
go help build
</syntaxhighlight>
</syntaxhighlight>
==<tt>build</tt>==
==<span id='Build_an_Executable_with_go_build'></span><span id='Package_without_Module_Support'></span><span id='Package_within_a_Module'></span><tt>build</tt>==
The <code>build</code> command compiles one or more packages. If a [[Go_Packages#The_main_Package|"main" package]] is among the arguments, the tool creates an executable as described [[#Build_an_Executable_with_go_build|below]]. The following flags apply:{{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}
{{Internal|go build#Overview|<tt>go build</tt>}}
<font color=darkkhaki>TO DEPLETE: [[Go_Commands_-_build]]</font>
===Build an Executable with <tt>go build</tt>===
<syntaxhighlight lang='bash'>
go build [options] <main-package-import-path>
</syntaxhighlight>
Note that depending on whether the package is part of module or not, the main package import path may include the [[Go_Modules#Module_Path_.28Module_Name.29|module path]].


The executable is placed in the directory <code>go build</code> is executed from.
==<span id='Build_and_Install_an_Executable_with_go_install'></span><span id='Package_without_Module_Support_2'></span><span id='Package_within_a_Module_2'></span><span id='Build_and_Install_Package_Object_Files'></span><span id='Package_without_Module_Support_3'></span><span id='Package_within_a_Module_3'></span><tt>install</tt>==
{{Internal|go install#Overview|<tt>go install</tt>}}


The name of the executable is given by the last segment of the main package import path, and it can be configured with the <code>-o</code> command line option. The argument of <code>-o</code> can be the new name of the executable file, in which case the executable will be written in the current directory, or an absolute or relative path, in which case the executable, named after the last segment of the path, will be written at the given path.
==<tt>run</tt>==
 
The <code>run</code> command compiles the specified packages or files by delegating to <code>[[#build|go build]]</code> and then runs the executable. There must be a <code>main</code> for an executable to be generated.
====<span id='build_PwMS'></span>Package without Module Support====
In case of a package without module support, with the <code>go</code> tool configured in [[Go_Language_Modularization#Module-Aware_or_GOPATH_Mode|GOPATH mode]] (<code>GOPATH</code> configured to include the parent of the <code>src</code> directory and <code>GO111MODULE</code> set to "auto"), and with this directory layout:
<font size=-2>
.
└─ src
    └─ a
       └─ b
        └─ c
            └─ main.go <font color=teal># package main</font>
</font>
the executable is built with:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
go build a/b/c
cd $PROJECT_DIR
go run ./src/main/main.go some-arg-1 some-arg-2
</syntaxhighlight>
</syntaxhighlight>
The executable will be named "c", based on the last segment of the package import path and will be place in the directory <code>go build</code> was executed from. To change the name of the executable, use the <code>-o</code> option:
The first argument that does not end in <code>.go</code> is assumed to be the beginning of the list of command line arguments of the executable.
<syntaxhighlight lang='bash'>
go build -o blue a/b/c
</syntaxhighlight>
This will create an executable named "blue".


====<span id='build_PwM'></span>Package within a Module====
<font color=darkkhaki>Is the above true though? The following command runs fine, where "example.com/experimental-go-module/cmd/gotest" is the package path of a "main" package inside of the "example.com/experimental-go-module" module. No argument ends in <code>.go</code>, yet it works:
An <code>a/b/c</code> main package with a similar layout, but this time included within an <code>example.com</code> module
<font size=-2>
.
├─ a
│  └─ b
│    └─ c
│        └─ main.go <font color=teal># package main</font>
└─ go.mod
</font>
can have its executable built with:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
go build [-o blue] example.com/a/b/c
go run example.com/experimental-go-module/cmd/gotest
</syntaxhighlight>
</syntaxhighlight>
==<tt>install</tt>==
<code>go install</code> is similar to <code>[[#build|go build]]</code> except that is saves the compiled code in form of [[Go_Language#Object_File|object files]] and possibly binary executables, locally for each packages instead of discarding it. The shared flags describe here apply: {{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}
<font color=darkkhaki>If executed from a git workarea, there is underlying git interaction.</font>
===Build and Install an Executable with <tt>go install</tt>===
<syntaxhighlight lang='bash'>
go install [options] <main-package-import-path>
</syntaxhighlight>
Note that depending on whether the package is part of module or not, the main package import path may include the [[Go_Modules#Module_Path_.28Module_Name.29|module path]].
The name of the executable is given by the last segment of the main package import path and cannot be changed with <code>-o</code> option, as in the case of the <code>[[#build|go build]]</code> command. Because of this detail, <code>go build</code> is probably a better way to build executables, if you want to change the name of the executable.
<span id='Executable_Placement'></span>The executable is placed under <code>${GOBIN}</code> directory if the <code>[[Go_Environment_Variables#GOBIN|GOBIN]]</code> environment variable is set, or under <code>${GOPATH}/bin</code> otherwise. The default value for <code>${GOPATH}</code> is <code>~/go</code>. For more details see <code>[[Go_Environment_Variables#GOPATH|GOPATH]]</code>.
====<span id='install_exec_PwMS'></span>Package without Module Support====
In case of a package without module support, with the <code>go</code> tool configured in [[Go_Language_Modularization#Module-Aware_or_GOPATH_Mode|GOPATH mode]] (<code>GOPATH</code> configured to include the parent of the <code>src</code> directory and <code>GO111MODULE</code> set to "auto"), and with this directory layout:
<font size=-2>
.
└─ src
    └─ a
       └─ b
        └─ c
            └─ main.go <font color=teal># package main</font>
</font>
the executable is built with:
<syntaxhighlight lang='bash'>
go install a/b/c
</syntaxhighlight>
The executable will be named "c", based on the last segment of the package import path and will be place in a directory determined by the rules described [[#Executable_Placement|above]].
Unlike <code>go build</code>, <code>go install</code> does not accept an <code>-o</code> option to change the name of the executable.
====<span id='install_exec_PwM'></span>Package within a Module====
An <code>a/b/c</code> main package with a similar layout, but this time included within an <code>example.com</code> module
<font size=-2>
.
├─ a
│  └─ b
│    └─ c
│        └─ main.go <font color=teal># package main</font>
└─ go.mod
</font>
</font>
can have its executable built with:
<syntaxhighlight lang='bash'>
go install example.com/a/b/c
</syntaxhighlight>
The executable is named based on the last sentiment of the package import path and it placed in a directory determined by the rules described [[#Executable_Placement|here]].
===Build and Install Package Object Files===
====<span id='install_object_PwMS'></span>Package without Module Support====
<code>[[Go_Environment_Variables#GOPATH|GOPATH]]</code> and <code>[[Go_Environment_Variables#GO111MODULE|GO111MODULE]]</code> should be configured as described in the [[#install_exec_PwMS|Package without Module Support]] executable <code>install</code> section, above. The package object file is built and installed with:
<syntaxhighlight lang='bash'>
go install <package-import-path>
</syntaxhighlight>
will compile and install [[Go_Language#Object_File|object files]] under <code>${[[Go_Environment_Variables#GOPATH|GOPATH]]}/pkg/${[[Go_Environment_Variables#GOOS|GOOS]]}_${[[Go_Environment_Variables#GOARCH|GOARCH]]}/<import-path></code>.
If the package specified as argument has dependency packages, <code>go install</code> will correctly locate and compile the source files for both the dependent package and all dependency packages identified walking the transitive dependency graph. If any of the dependencies fails to compile, the installation process will fail. However, only the object file corresponding to specified package will be written in <code>${GOPATH}/pkg</code>. To install the object files for the entire dependency chain, the packages have to be explicitly specified on the command line.
If the <code>pkg</code> subdirectory does not exist, it will be created. The <code>go install</code> can be run from the <code>${GOPATH}</code> directory, or from some any other directory. As long the <code>GOPATH</code> and <code>GO111MODULE</code> are correctly set, the results will be the same.
====<span id='install_object_PwM'></span>Package within a Module====


==<tt>run</tt>==
The <code>run</code> command compiles the specified packages or files by delegating to <code>[[#build|go build]]</code> and then runs the executable. There must be a <code>main</code> for an executable to be generated.
<syntaxhighlight lang='bash'>
cd $PROJECT_DIR
go run ./src/main/main.go some-arg-1 some-arg-2
</syntaxhighlight>
The first argument that does not end in <code>.go</code> is assumed to be the beginning of the list of command line arguments of the executable.
The shared flags described here apply: {{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}
The shared flags described here apply: {{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}


Line 145: Line 50:
go clean -fuzzcache
go clean -fuzzcache
</syntaxhighlight>
</syntaxhighlight>
==<tt>link</tt>==
{{Internal|go tool link#Overview|<tt>go tool link</tt>}}


==<tt>doc</tt>==
==<tt>doc</tt>==
The <code>doc</code> command prints documentation for a package or a package member:
{{Internal|Go_doc#Overview|<tt>go doc</tt>}}
<syntaxhighlight lang='go'>
 
go doc time
==<span id='fmt'></span><tt>fmt</tt> (<tt>gofmt</tt>)==
</syntaxhighlight>
{{Internal|Go_fmt#Overview|<tt>go fmt</tt>}}
<syntaxhighlight lang='go'>
go doc time.Since
</syntaxhighlight>


==<tt>fmt</tt>==
The <code>fmt</code> ("format") command formats source code files.
==<tt>get</tt>==
==<tt>get</tt>==
The <code>get</code> command downloads packages and installs them. The shared flags described here apply: {{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}
The <code>get</code> command downloads packages and installs them, possibly updating a local obsolete version. It does that by connecting to the remote repository that maintains the package source code and downloading the source tree locally. <code>get</code> is the preferred way to update <code>go.mod</code> with a new dependency:
{{Internal|Go.mod#Adding_a_Dependency_to_a_Module|<tt>go.mod</tt> &#124; <tt>go get</tt>}}
Once <code>go.mod</code> has been updated by <code>go get</code>, the package's import pat can be used in the project's <code>[[Go_Packages#Import_Statement|import]]</code> statements.
 
<code>go get</code> is sensitive to the Git configuration present in <code>~/.gitconfig</code>, especially repository configuration:
<font size=-2>
[url "git@github.example.com:some-repo"]
        insteadOf = https&#58;//github.example.com/some-repo
</font>
The shared flags described here apply: {{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}
===Problems with <tt>get</tt>===
<font color=darkkhaki>The <code>import</code> statement drives <code>go get</code> but the <code>import</code> statement does not contain sufficient information to identify which revision of a package should be fetched any time <code>go get</code> is called. The possibility that <code>go get</code> can fetch a different version of code for any given package at any time makes supporting the Go tooling in any reproducible solution complicated and tedious.</font>
 
===Options===
====<tt>-u</tt>====
The <code>-u</code> flag instructs <code>get</code> to update modules providing dependencies of packages named on the command line to use newer minor or patch releases when available.
====<tt>-d</tt>====
Stop after downloading the package, do not install the package.
====<tt>-f</tt>====
Only valid when <code>[[#-u|-u]]</code> is set, forces <code>get -u</code> not to verify that each package has been checked out from the source control repository implied by its import path. This can be useful if the source is a local fork of the original.
 
====<tt>-fix</tt>====
Run the fix tool on the downloaded packages before resolving dependencies or building the code.
====<tt>-t</tt>====
Also download the packages required to build the tests for the specified packages.


==<tt>list</tt>==
==<tt>list</tt>==
The <code>list</code> command lists all installed packages. The shared flags described here apply: {{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}
{{Internal|Go_list#Overview|<tt>go list</tt>}}


==<tt>test</tt>==
==<tt>test</tt>==
The <code>test</code> command runs tests. The shared flags described here apply: {{Internal|Go_Tool_Shared_Flags#Overview|Shared Flags}}
{{Internal|Go test Command|<tt>go test</code> Command}}
For more details, see:
{{Internal|Go_Testing#Overview|Go Testing}}


==<tt>env</tt>==
==<tt>env</tt>==
The <code>env</code> command prints the effective values of the [[Go_Environment_Variables|environment variables]] relevant to the tool chain.
{{Internal|go env#Overview|<tt>go env</tt>}}
<syntaxhighlight lang='bash'>
go env GOOS GOARCH GOPATH
</syntaxhighlight>
==<tt>get</tt>==
The <code>get</code> command retrieve and update packages.


<font color=darkkhaki>TODO Addison-Wesley The Go Programming Language Section 10.7.2</font>
==<tt>mod</tt>==
==<tt>mod</tt>==
{{Internal|Go_Modules#go.mod|<tt>go.mod</tt>}}
{{Internal|go mod#Overview|<tt>go mod</tt>}}
Initialize a v0 or v1 module:
==<tt>vet</tt>==
<syntaxhighlight lang='bash'>
<font color=darkkhaki>
go mod init example.com/m
Deplete: [[Go Commands - vet|vet]]
</syntaxhighlight>
</font>
Initialize a v2 module:
==<tt>version</tt>==
<syntaxhighlight lang='bash'>
go mod init example.com/m/v2
</syntaxhighlight>
 
Inspect the code, look for module imports, download them and update <code>go.mod</code>.
<syntaxhighlight lang='bash'>
go mod tidy
</syntaxhighlight>
 
=TO DEPLETE=
<font color=darkkhaki>
<font color=darkkhaki>
Deplete:
Deplete [[Go Commands - version|version]]
* [[Go Concepts - Documentation#Reading_Documentation|doc]]
* [[Go Commands - fmt|fmt]]
* [[Go Commands - get|get]]
* [[Go Commands - version|version]]
* [[Go Commands - vet|vet]]
</font>
</font>

Latest revision as of 23:36, 5 July 2024

External

Internal

Overview

go is a command line tool with multiple uses: package manager, build tool and test driver. go manage packages in workspaces, query metadata about packages, print documentation, build, format, download, test, etc.

Shared Flags

Shared Flags

Commands

Help

go help <command>

go help build

build

go build

install

go install

run

The run command compiles the specified packages or files by delegating to go build and then runs the executable. There must be a main for an executable to be generated. 

cd $PROJECT_DIR
go run ./src/main/main.go some-arg-1 some-arg-2

The first argument that does not end in .go is assumed to be the beginning of the list of command line arguments of the executable.

Is the above true though? The following command runs fine, where "example.com/experimental-go-module/cmd/gotest" is the package path of a "main" package inside of the "example.com/experimental-go-module" module. No argument ends in .go, yet it works: 

go run example.com/experimental-go-module/cmd/gotest

The shared flags described here apply:

Shared Flags

clean

The shared flags described here apply:

Shared Flags

-cache

Clean the build cache: 

go clean -cache

-fuzzcache

Clean the fuzz cache: 

go clean -fuzzcache

link

go tool link

doc

go doc

fmt (gofmt)

go fmt

get

The get command downloads packages and installs them, possibly updating a local obsolete version. It does that by connecting to the remote repository that maintains the package source code and downloading the source tree locally. get is the preferred way to update go.mod with a new dependency:

go.mod | go get

Once go.mod has been updated by go get, the package's import pat can be used in the project's import statements.

go get is sensitive to the Git configuration present in ~/.gitconfig, especially repository configuration: 

[url "git@github.example.com:some-repo"]
       insteadOf = https://github.example.com/some-repo

The shared flags described here apply:

Shared Flags

Problems with get

The import statement drives go get but the import statement does not contain sufficient information to identify which revision of a package should be fetched any time go get is called. The possibility that go get can fetch a different version of code for any given package at any time makes supporting the Go tooling in any reproducible solution complicated and tedious.

Options

-u

The -u flag instructs get to update modules providing dependencies of packages named on the command line to use newer minor or patch releases when available.

-d

Stop after downloading the package, do not install the package.

-f

Only valid when -u is set, forces get -u not to verify that each package has been checked out from the source control repository implied by its import path. This can be useful if the source is a local fork of the original.

-fix

Run the fix tool on the downloaded packages before resolving dependencies or building the code.

-t

Also download the packages required to build the tests for the specified packages.

list

go list

test

go test Command

env

go env

mod

go mod

vet

Deplete: vet

version

Deplete version

Retrieved from "https://kb.novaordis.com/index.php?title=Go_Tool&oldid=111365"