From 02ef8fa5ddb8111aa8752ffb8267e67c4e209649 Mon Sep 17 00:00:00 2001 From: Steve Traut Date: Mon, 1 Mar 2021 10:42:43 -0500 Subject: _content/doc: fix module and tutorial bugs and clean up flow For golang/go#44241 - Fix issues 2, 3, 8, 16, 17, 18 from golang/go#44241 Other changes in multiple topics: - In markdown, replace HTML anchor tags with {#anchor} tags. - In a few places, add content to clarify that module path must be a location from which the module can be downloaded. - Where it was missing, add example.com domain to example module paths. Hopefully, this will reinforce the idea that the module path should typically include a domain. Docs will use something that looks like a domain name for module path. - Add more cross-references from tutorial to references for packages and commands. - Rewrite a few links so that they include the topic title, rather than simply inline text. Left those links whose destinations are references -- the item's name seems to suggest that a reference is at the destination. - Remove domain name from golang.org doc links, leaving root directory. Such as /cmd/go/* or /doc/modules/* - Add path up to root for all links in the same domain. Some were linking by file name only. - Change standard library links from golang.org to pkg.go.dev. Changes in the module tutorial: - Add text to help clarify that there should be a hello and greetings directory as siblings in their directory hierarchy. Some users thought one should be subordinate to the other. - Where needed, reorder steps so that `go mod init` is run before code is added. This is intended to reinforce the importance of the module's presence. - In require/replace steps, have the user use `go mod edit` rather than editing the go.mod file in an editor. The tools are more likely to yield a functioning result. - Where possible/appropriate, change module directive link destinations from "Modules reference" to go.mod reference. - Change "run the code" steps so that they all use `go run .` rather than `go build` or `go run `. This removes the impedance of explanation and more commands, while moving the explanation of `go build` and `go install` to a separate topic where they share a clearer context. - Add a "Conclusion" topic with a few links. The tutorial ended rather abruptly before. - Minor edits to remove some redundant language. Change-Id: I93055035d73c362ba73edea458fc53bc45e66512 Reviewed-on: https://go-review.googlesource.com/c/website/+/297531 Trust: Steve Traut Run-TryBot: Steve Traut TryBot-Result: Go Bot Reviewed-by: Jay Conrod --- _content/doc/tutorial/call-module-code.html | 224 ++++++++++++++-------------- 1 file changed, 114 insertions(+), 110 deletions(-) (limited to '_content/doc/tutorial/call-module-code.html') diff --git a/_content/doc/tutorial/call-module-code.html b/_content/doc/tutorial/call-module-code.html index 3c3602b8..bce43d72 100644 --- a/_content/doc/tutorial/call-module-code.html +++ b/_content/doc/tutorial/call-module-code.html @@ -4,7 +4,7 @@ }-->

- In the previous section, you created a + In the previous section, you created a greetings module. In this section, you'll write code to make calls to the Hello function in the module you just wrote. You'll write code you can execute as an application, and which calls code in the @@ -13,7 +13,7 @@

    @@ -22,8 +22,16 @@ is where you'll write your caller.

    - For example, if your current directory in the command prompt is the - greetings directory, you could use the following commands: + After you create this directory, you should have both a hello and a + greetings directory at the same level in the hierarchy, like so: +

    + 
    <home>/
+ |-- greetings/
+ |-- hello/
    + +

    + For example, if your command prompt is in the greetings directory, you + could use the following commands: 

    @@ -35,7 +43,28 @@ cd hello
   
 
   
  1. 
-    In your text editor (in the hello directory), create a file in which to
+    Enable dependency tracking for the code you're about to write.
+
+    
    
+      To enable dependency tracking for your code, run the
+      go mod init command, giving it the name of the module
+        your code will be in.
    
+
+    
    
+        For the purposes of this tutorial, use example.com/hello
+        for the module path.
+    
    
+
+    
    +$ go mod init example.com/hello
+go: creating new go.mod: module example.com/hello
+
    
+  
    2. 
+
+  
  2. 
+    In your text editor, in the hello directory, create a file in which to
     write your code and call it hello.go.
   
    3. 
 
@@ -61,8 +90,7 @@ func main() {
     message := greetings.Hello("Gladys")
     fmt.Println(message)
 }
-
    +

    In this code, you: @@ -71,16 +99,16 @@ func main() {

    • Declare a main package. In Go, code executed as an - application must go in a main package. + application must be in a main package.
    • Import two packages: example.com/greetings and - fmt. This gives your code access to functions in those - packages. Importing example.com/greetings (the package - contained in the module you created earlier) gives you access to the - Hello function. You also import fmt, with - functions for handling input and output text (such as printing text to - the console). + the fmt package. This + gives your code access to functions in those packages. Importing + example.com/greetings (the package contained in the module + you created earlier) gives you access to the Hello + function. You also import fmt, with functions for handling + input and output text (such as printing text to the console).
    • Get a greeting by calling the greetings package’s @@ -90,148 +118,124 @@ func main() {
    • - Create a new module for this hello package. + Edit the example.com/hello module to use your local + example.com/greetings module.

      - From the command line at the hello directory, run the - go mod init command, giving it the name of the module your - code will be in (here, just use "hello"). -

      - - 
      -$ go mod init hello
-go: creating new go.mod: module hello
-
      -
      • - -
    • - Edit the hello module to use the unpublished greetings module. - -

      - For production use, you’d publish your modules on a server, either inside - your company or on the internet, and the Go command will download them - from there. For now, you need to adapt the caller's module so it can find - the greetings code on your local file system. + For production use, you’d publish the example.com/greetings + module from its repository (with a module path that reflected its published + location), where Go tools could find it to download it. + For now, because you haven't published the module yet, you need to adapt + the example.com/hello module so it can find the + example.com/greetings code on your local file system.

      - To do that, make a small change to hello module’s go.mod - file. + To do that, use the + go + mod edit command to edit the example.com/hello + module to redirect Go tools from its module path (where the module isn't) + to the local directory (where it is).

      1. - In the hello directory, open the go.mod file, change it so that it looks - like the following, and save the file. + From the command prompt in the hello directory, run the following + command: + + 
        +$ go mod edit -replace=example.com/greetings=../greetings
+
        + +

        + The command specifies that example.com/greetings should be + replaced with ../greetings for the purpose of locating the + dependency. After you run the command, the go.mod file in the hello + directory should include a + replace directive: + 

        -module hello
+module example.com/hello
 
-go 1.14
+go 1.16
 
 replace example.com/greetings => ../greetings
        - -

        - Here, the - - replace directive - - tells Go to replace the module path (the URL - example.com/greetings) with a path you specify. In this - case, that's a greetings directory next to the hello directory. -

      2. - In the hello directory, run go build to make Go locate the - module and add it as a dependency to the go.mod file. + From the command prompt in the hello directory, run the + + go mod tidy command to synchronize the + example.com/hello module's dependencies, adding those + required by the code, but not yet tracked in the module. - 
        -$ go build
+        
        $ go mod tidy
 go: found example.com/greetings in example.com/greetings v0.0.0-00010101000000-000000000000
-
        
-
        3. - -
      3. - Look at go.mod again to see the changes made by go build, - including the require directive Go added. + +

        + After the command completes, the example.com/hello + module's go.mod file should look like this: +

        - 
        -module hello
+        
        module example.com/hello
 
-go 1.14
+go 1.16
 
 replace example.com/greetings => ../greetings
 
-require example.com/greetings v0.0.0-00010101000000-000000000000
-
        
+require example.com/greetings v0.0.0-00010101000000-000000000000

        - To build the module, Go found the local code in the ../greetings - directory, then added a - - require directive - - to specify that hello is dependent on (requires) - example.com/greetings. You created this dependency when - you imported the greetings package (contained in the - greetings module) in hello.go. The replace directive - tells Go where to find the greetings module, because it - isn't published yet. + The command found the local code in the greetings directory, then + added a require + directive to specify that example.com/hello + requires example.com/greetings. You created this + dependency when you imported the greetings package in + hello.go. +

        +

        + The number following the module path is a pseudo-version number + -- a generated number used in place of a semantic version number (which + the module doesn't have yet).

        -

        - To reference a published module, a go.mod file would omit the - replace directive and use a - require directive with a tagged version number at the - end. + To reference a published module, a go.mod file would + typically omit the replace directive and use a + require directive with a tagged version number at the end. 

        require example.com/greetings v1.1.0
        + +

        For more on version numbers, see + Module version numbering.

      -
      • -
    • - In the hello directory, run the hello executable - (created by go build) to confirm that the code works. -
        -
      • - On Linux or Mac: + At the command prompt in the hello directory, run your code to + confirm that it works. - 
        -$ ./hello
-Hi, Gladys. Welcome!
-
        -
        • - -
      • - On Windows: - - 
        -$ hello.exe
+    
        +$ go run .
 Hi, Gladys. Welcome!
-
        
-
        • -
      +

- Congrats! You've written two functioning modules. In the tutorial's - next topic, you'll add some error handling. + Congrats! You've written two functioning modules. +

+ +

+ In the next topic, you'll add some error handling.

- < Create a Go module - Return and handle an error >

-- cgit v1.3