Go Concepts - Runtime: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(61 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Internal=
=Executables vs. Libraries=


* [[Go Concepts#Subjects|Go Concepts]]
''Executables'' are native code programs that can be run directly from command line.


=Environment Variables=
''Libraries'' are collection of native code that can be used by other programs.


==<tt>GOPATH</tt>==
==Compiling an Executable==


* External: <tt>go help gopath</tt>.
According to the specifications (https://golang.org/ref/spec#Program_execution), a complete program is created by linking a single, unimported package called the ''main'' package with all the package it imports, transitively. [[Go_Language_Modularization#The_.22main.22_Package|The main package]] must be named "main". The main package must declare a [[Go Concepts - Functions#The_main.28.29_Function|function named <tt>main()</tt> that takes no arguments and returns no value]]. The <tt>main()</tt> function is the entry point in the program. If the "main" package does not contain a <tt>main()</tt> function, the build tool won't produce an executable:


<tt>GOPATH</tt> is used by the compiler to locate source files for the [[Go Concepts - Packages#Overview|package]]s listed by the [[Go Keyword import|import]] statements in source files being compiled.
<pre>
runtime.main: call to external function main.main
runtime.main: main.main: not defined
runtime.main: undefined: main.main
</pre>


<tt>GOPATH</tt> content lists directories on the local file system. On UNIX, the value is a colon-separated string. On Windows, the value is a semicolon-separated string. The compiler loops over the values listed in <tt>GOPATH</tt>, in order, appends <tt>/src/<required-package-name></tt> to those values and looks into the directories whose name are thus generated for source files that belong to the required packages. This is why it is important that the package and the directory containing the package sources have the same name: if they don't, the compilation fails.
The program execution begins by initializing the main package and invoking the <tt>main()</tt> function. Then the function invocation returns, the program exists. It does not wait for other (non-<tt>main</tt>) goroutines to complete.


Note that the name of the source file that contains the <tt>main()</tt> function does NOT have to be "main.go". It could be any legal file name. The executable will be created under the name of the file that contains the <tt>main()</tt> function.


The simplest possible executable named <tt>example</tt> can be created as follows:


Declare an <tt>example.go</tt> that defines the "main" package and contains the <tt>main()</tt> function:


===<tt>GOPATH</tt> Example===
<pre>
package main


import "fmt"


func main() {
    fmt.Println("I am example")
}
</pre>


Build the executable:


<pre>
go build ./example.go
</pre>


 
The compiler will create an <tt>example</tt> executable.
 
 
The Go path is used to resolve import statements.
It is implemented by and documented in the go/build package.
 
The GOPATH environment variable lists places to look for Go code.
On Unix, the value is a colon-separated string.
On Windows, the value is a semicolon-separated string.
On Plan 9, the value is a list.
 
GOPATH must be set to get, build and install packages outside the
standard Go tree.
 
Each directory listed in GOPATH must have a prescribed structure:
 
The src directory holds source code.  The path below src
determines the import path or executable name.
 
The pkg directory holds installed package objects.
As in the Go tree, each target operating system and
architecture pair has its own subdirectory of pkg
(pkg/GOOS_GOARCH).
 
If DIR is a directory listed in the GOPATH, a package with
source in DIR/src/foo/bar can be imported as "foo/bar" and
has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
 
The bin directory holds compiled commands.
Each command is named for its source directory, but only
the final element, not the entire path.  That is, the
command with source in DIR/src/foo/quux is installed into
DIR/bin/quux, not DIR/bin/foo/quux.  The "foo/" prefix is stripped
so that you can add DIR/bin to your PATH to get at the
installed commands.  If the GOBIN environment variable is
set, commands are installed to the directory it names instead
of DIR/bin. GOBIN must be an absolute path.
 
Here's an example directory layout:
 
    GOPATH=/home/user/gocode
 
    /home/user/gocode/
        src/
            foo/
                bar/              (go code in package bar)
                    x.go
                quux/              (go code in package main)
                    y.go
        bin/
            quux                  (installed command)
        pkg/
            linux_amd64/
                foo/
                    bar.a          (installed package object)
 
Go searches each directory listed in GOPATH to find source code,
but new packages are always downloaded into the first directory
in the list.
 
See https://golang.org/doc/code.html for an example.
 
Internal Directories
 
Code in or below a directory named "internal" is importable only
by code in the directory tree rooted at the parent of "internal".
Here's an extended version of the directory layout above:
 
    /home/user/gocode/
        src/
            crash/
                bang/              (go code in package bang)
                    b.go
            foo/                  (go code in package foo)
                f.go
                bar/              (go code in package bar)
                    x.go
                internal/
                    baz/          (go code in package baz)
                        z.go
                quux/              (go code in package main)
                    y.go
 
 
The code in z.go is imported as "foo/internal/baz", but that
import statement can only appear in source files in the subtree
rooted at foo. The source files foo/f.go, foo/bar/x.go, and
foo/quux/y.go can all import "foo/internal/baz", but the source file
crash/bang/b.go cannot.
 
See https://golang.org/s/go14internal for details.
 
Vendor Directories
 
Go 1.6 includes support for using local copies of external dependencies
to satisfy imports of those dependencies, often referred to as vendoring.
 
Code below a directory named "vendor" is importable only
by code in the directory tree rooted at the parent of "vendor",
and only using an import path that omits the prefix up to and
including the vendor element.
 
Here's the example from the previous section,
but with the "internal" directory renamed to "vendor"
and a new foo/vendor/crash/bang directory added:
 
    /home/user/gocode/
        src/
            crash/
                bang/              (go code in package bang)
                    b.go
            foo/                  (go code in package foo)
                f.go
                bar/              (go code in package bar)
                    x.go
                vendor/
                    crash/
                        bang/      (go code in package bang)
                            b.go
                    baz/          (go code in package baz)
                        z.go
                quux/              (go code in package main)
                    y.go
 
The same visibility rules apply as for internal, but the code
in z.go is imported as "baz", not as "foo/vendor/baz".
 
Code in vendor directories deeper in the source tree shadows
code in higher directories. Within the subtree rooted at foo, an import
of "crash/bang" resolves to "foo/vendor/crash/bang", not the
top-level "crash/bang".
 
Code in vendor directories is not subject to import path
checking (see 'go help importpath').
 
When 'go get' checks out or updates a git repository, it now also
updates submodules.
 
Vendor directories do not affect the placement of new repositories
being checked out for the first time by 'go get': those are always
placed in the main GOPATH, never in a vendor subtree.
 
In Go 1.5, as an experiment, setting the environment variable
GO15VENDOREXPERIMENT=1 enabled these features.
As of Go 1.6 they are on by default. To turn them off, set
GO15VENDOREXPERIMENT=0. In Go 1.7, the environment
variable will stop having any effect.
 
See https://golang.org/s/go15vendor for details.
 
==<tt>GOROOT</tt>==
 
=Compiling an Executable=
 
<font color=red>TODO, more here: <tt>go build</tt> creates an executable only if among the packages being compiled there is a <tt>main</tt> package, and the package contains a <tt>main()</tt> function.</font>

Latest revision as of 20:44, 7 September 2023

Executables vs. Libraries

Executables are native code programs that can be run directly from command line.

Libraries are collection of native code that can be used by other programs.

Compiling an Executable

According to the specifications (https://golang.org/ref/spec#Program_execution), a complete program is created by linking a single, unimported package called the main package with all the package it imports, transitively. The main package must be named "main". The main package must declare a function named main() that takes no arguments and returns no value. The main() function is the entry point in the program. If the "main" package does not contain a main() function, the build tool won't produce an executable: 

runtime.main: call to external function main.main
runtime.main: main.main: not defined
runtime.main: undefined: main.main

The program execution begins by initializing the main package and invoking the main() function. Then the function invocation returns, the program exists. It does not wait for other (non-main) goroutines to complete.

Note that the name of the source file that contains the main() function does NOT have to be "main.go". It could be any legal file name. The executable will be created under the name of the file that contains the main() function.

The simplest possible executable named example can be created as follows:

Declare an example.go that defines the "main" package and contains the main() function: 

package main

import "fmt"

func main() {
    fmt.Println("I am example")
}

Build the executable: 

go build ./example.go

The compiler will create an example executable.

Retrieved from "https://kb.novaordis.com/index.php?title=Go_Concepts_-_Runtime&oldid=100713"