dlv

Documentation

Overview

Package dlv allows to run any binaries with latest version of delve.

To make it works:

1. compile your code with -gcflags "all=-N -l"
2. Use NewDlvRunner function to encapsulate your main function.

Tips

Don't bring delve in production: use compile tags

Refactor your code in such way you can easily call the main workload as a one-liner in `main()` function. Then use compile tag to ensure that the actual main function will wrap the workload in delve only if the debug flag is used at compile time:

go build -gcflags "all=-N -l" -tags debug path/to/my/package

It can be done through having two main files in package main, one named `main.go` and one name `main_debug.go`. The former will be compiled only if there is no debug tag, the latter only if there is a debug tag. Making mistake with tags would end up with two main functions, which will cause a compile error (better for avoiding shipment of debug binaries in production).

Example

main_debug.go

//go:build debug

package main

 import (
 "github.com/juju/juju/internal/dlv"
 "github.com/juju/juju/internal/dlv/config"
 )

func main() {
   os.Exit(dlv.NewDlvRunner(dlv.NewDlvRunner(
   dlv.Headless(),
   dlv.WithApiVersion(2),
   dlv.WithPort(1122),
   dlv.WaitDebugger()))(mainArgs)(os.Args))
}

main.go

//go:build !debug

package main

import (
   "os"
)

func main() {
   os.Exit(mainArgs(os.Args))
}

func mainArgs(args []string) int { /* ... */ }

Index

• func NewDlvRunner(opts ...Option) func(main MainWithArgs) MainWithArgs
• type Config
• type MainWithArgs
• type Option
  • func Headless() Option
  • func NoWait() Option
  • func WaitDebugger() Option
  • func With(key string, value ...any) Option
  • func WithApiVersion(version int) Option
  • func WithLogger(logger logger.Logger) Option
  • func WithPort(port int) Option
  • func WithSidecar(sidecar func() error) Option
  • func WithSocket(socket string) Option

Functions

func NewDlvRunner

func NewDlvRunner(opts ...Option) func(main MainWithArgs) MainWithArgs

NewDlvRunner wraps a MainWithArgs function to enable debugging.

It works in two phases: At first call, it launches the delve command `exec` with the current binary. However, before the call it sets an environment variable DELVE_ANYTHING_NO_DEBUG. At the second call, DELVE_ANYTHING_NO_DEBUG is set, so it just returns the "normal" main.

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config is a type that represents a map of configuration options where the key is a string and the value can be any type. They are passed to Delve as command line option.

type MainWithArgs

type MainWithArgs func(args []string) int

MainWithArgs is a type representing a function that takes command-line arguments as input and returns an exit code.

type Option

type Option func(*Config)

Option describes a functional option for configuring a Config instance.

func Headless

func Headless() Option

Headless sets the "headless" option to true, which runs delve in server mode

func NoWait

func NoWait() Option

NoWait set the debugger to continue execution immediately. Debugged application wouldn't wait for a debugger to be attached.

func WaitDebugger

func WaitDebugger() Option

WaitDebugger set the "continue" option to false, the debugged application will wait until a debugger is attached, after having generating a first log indicating on which endpoint it listens.

func With

func With(key string, value ...any) Option

With sets a key-value pair in the Config struct. Handles zero, one, or multiple values for a given key.

func WithApiVersion

func WithApiVersion(version int) Option

WithApiVersion sets the API version in the options with the specified version number.

func WithLogger

func WithLogger(logger logger.Logger) Option

WithLogger sets a custom logger to be used in the configuration.

func WithPort

func WithPort(port int) Option

WithPort configures the listening port for the application by setting the "listen" option to the specified port.

func WithSidecar

func WithSidecar(sidecar func() error) Option

WithSidecar adds a function to be executed as a sidecar process in the Config instance.

func WithSocket

func WithSocket(socket string) Option

WithSocket configures a unix socket address to connect to the .