From 01f5b3c8d0a2f2ee43cc327b3a6d6b7b7ae53ae5 Mon Sep 17 00:00:00 2001
From: Derek Parker <parkerderek86@gmail.com>
Date: Thu, 4 Jan 2018 04:50:44 -0800
Subject: [PATCH] Documentation: Improve link layout, add getting started doc
 (#1064)

Improve the link ordering for the main README and add a
"Getting Started" doc with basic usage information for new users.
---
 Documentation/cli/getting_started.md | 90 ++++++++++++++++++++++++++++
 README.md                            |  3 +-
 2 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/cli/getting_started.md

diff --git a/Documentation/cli/getting_started.md b/Documentation/cli/getting_started.md
new file mode 100644
index 00000000..522fd399
--- /dev/null
+++ b/Documentation/cli/getting_started.md
@@ -0,0 +1,90 @@
+# Getting Started
+
+Delve aims to be a very simple and powerful tool, but can be confusing if you're
+not used to using a source level debugger in a compiled language. This document
+will provide all the information you need to get started debugging your Go
+programs.
+
+## Debugging 'main' packages
+
+The first CLI subcommand we will explore is `debug`. This subcommand can be run
+without arguments if you're in the same directory as your `main` package,
+otherwise it optionally accepts a package path.
+
+For example given this project layout:
+
+```
+.
+├── github.com/me/foo
+├── cmd
+│   └── foo
+│       └── main.go
+├── pkg
+│   └── baz
+│       ├── bar.go
+│       └── bar_test.go
+```
+
+If you are in the directory `github.com/me/foo/cmd/foo` you can simple run `dlv debug`
+from the command line. From anywhere else, say the project root, you can simply
+provide the package: `dlv debug github.com/me/foo/cmd/foo`.
+
+Invoking that command will cause Delve to compile the program in a way most
+suitable for debugging, then it will execute and attach to the program and begin
+a debug session. Now, when the debug session has first started you are at the
+very beginning of the program's initialization. To get to someplace more useful
+you're going to want to set a breakpoint or two and continue execution to that
+point.
+
+For example, to continue execution to your programs `main` function:
+
+```
+$ dlv debug github.com/me/foo/cmd/foo
+Type 'help' for list of commands.
+(dlv) break main.main
+Breakpoint 1 set at 0x49ecf3 for main.main() ./test.go:5
+(dlv) continue
+> main.main() ./test.go:5 (hits goroutine(1):1 total:1) (PC: 0x49ecf3)
+     1:	package main
+     2:	
+     3:	import "fmt"
+     4:	
+=>   5:	func main() {
+     6:		fmt.Println("delve test")
+     7:	}
+(dlv) 
+```
+
+## Debugging tests
+
+Given the same directory structure as above you can debug your code by executing
+your test suite. For this you can use the `dlv test` subcommand, which takes the
+same optional package path as `dlv debug`, and will also build the current
+package if not given any argument.
+
+```
+$ dlv test github.com/me/foo/pkg/baz
+Type 'help' for list of commands.
+(dlv) funcs test.Test*
+/home/me/go/src/github.com/me/foo/pkg/baz/test.TestHi
+(dlv) break TestHi
+Breakpoint 1 set at 0x536513 for /home/me/go/src/github.com/me/foo/pkg/baz/test.TestHi() ./test_test.go:5
+(dlv) continue
+> /home/me/go/src/github.com/me/foo/pkg/baz/test.TestHi() ./bar_test.go:5 (hits goroutine(5):1 total:1) (PC: 0x536513)
+     1:	package baz
+     2:	
+     3:	import "testing"
+     4:	
+=>   5:	func TestHi(t *testing.T) {
+     6:		t.Fatal("implement me!")
+     7:	}
+(dlv) 
+```
+
+As you can see, we began debugging the test binary, found our test function via
+the `funcs` command which takes a regexp to filter the list of functions, set a
+breakpoint and then continued execution until we hit that breakpoint.
+
+For more information on subcommands you can use type `dlv help`, and once in a
+debug session you can see all of the commands available to you by typing `help`
+at any time.
diff --git a/README.md b/README.md
index 7969cb32..9031b74d 100644
--- a/README.md
+++ b/README.md
@@ -10,8 +10,9 @@ The Github issue tracker is for **bugs** only. Please use the [developer mailing
 
 ### About Delve
 
+- [Installation](Documentation/installation)
+- [Getting Started](Documentation/cli/getting_started)
 - [Documentation](Documentation)
-- [Building](Documentation/installation)
 - [Contributing](CONTRIBUTING.md)
 
 Delve is a debugger for the Go programming language. The goal of the project is to provide a simple, full featured debugging tool for Go. Delve should be easy to invoke and easy to use. Chances are if you're using a debugger, things aren't going your way. With that in mind, Delve should stay out of your way as much as possible.
-- 
GitLab