{"id":19493317,"url":"https://github.com/negrel/debuggo","last_synced_at":"2025-04-25T20:31:10.291Z","repository":{"id":57533852,"uuid":"260956969","full_name":"negrel/debuggo","owner":"negrel","description":":small_red_triangle: Debugging package that leverage the power of conditional compilation.","archived":false,"fork":false,"pushed_at":"2021-01-07T19:48:11.000Z","size":848,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-04T03:11:42.548Z","etag":null,"topics":["debugging","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/negrel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-03T15:18:51.000Z","updated_at":"2021-07-05T12:35:10.000Z","dependencies_parsed_at":"2022-09-26T18:21:20.348Z","dependency_job_id":null,"html_url":"https://github.com/negrel/debuggo","commit_stats":null,"previous_names":["negrel/debugo"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fdebuggo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fdebuggo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fdebuggo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/negrel%2Fdebuggo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/negrel","download_url":"https://codeload.github.com/negrel/debuggo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250890319,"owners_count":21503478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugging","go","golang"],"created_at":"2024-11-10T21:25:16.452Z","updated_at":"2025-04-25T20:31:09.836Z","avatar_url":"https://github.com/negrel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :small_red_triangle: Debuggo\n\n\u003cp\u003e\n\t\u003ca href=\"https://pkg.go.dev/github.com/negrel/debuggo\"\u003e\n\t\t\u003cimg alt=\"PkgGoDev\" src=\"https://pkg.go.dev/badge/github.com/negrel/debuggo\"\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://goreportcard.com/report/github.com/negrel/debuggo\"\u003e\n\t\t\u003cimg alt=\"Go Report Card\" src=\"https://goreportcard.com/badge/github.com/negrel/debuggo\"\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e\n\n*Debugging packages that leverage the power of conditional compilation.*\n\n**Debuggo** made of the following packages:\n- [`assert`](#the-assert-package)\n- [`log`](#the-log-package)\n\n## Why ?\n\nRecently, I was looking at the source code of [flutter](https://flutter.dev/) to have a deeper understanding of what's\ngoing on inside. This is where I discovered the assert function of dart, *assert* is used everywhere in\n[flutter](https://flutter.dev/), every single **class** use it at least once.\n\n*Definition of assert from [dart.dev](https://dart.dev/guides/language/language-tour#assert)* :\n\n\u003e During development, use an assert statement — `assert(condition, optionalMessage)`; — to disrupt normal execution if a\n\u003e boolean condition is false.\n\n\u003e In production code, assertions are ignored, and the arguments to `assert` aren’t evaluated.\n\nThis function is pretty basic, but it allows developers to make assertions in classes methods without adding overhead\nto production binary. Take a look at this part of the definition :\n\n\u003eIn **production** code, assertions are **ignored**, and the arguments to `assert` aren’t **evaluated**.\n\nAssertions are removed for the production, thereby, we can write development code without **increasing** the size or\n**slowing down** our production binaries.\n\nThis is exactly what we tried to reproduce in `pkg/assert`:\n\n## The `assert` package\nThe `assert` package is a modified version of the excellent [`testify/assert`](https://github.com/stretchr/testify)\npackage. Thus, you can use assert functions outside tests.\n\n### Features\n- Prints friendly, easy to read failure descriptions  \n- Allows for very readable code\n- Optionally annotate each assertion with a message\n\nTake a look at [examples/assert/main.go](https://github.com/negrel/debuggo/blob/master/examples/assert/main.go). By\ndefault, assertions are disable.\n\n```bash\n# Let's run the example\n$ go run .\nIn one hour the temperature will be -1 °C\n\n\n\n# The program didn't panic because assertions were disabled\n# Let's run the exampe with assertions enabled now.\n$ go run -tags assert .\npanic: \n%s      Error Trace:    proc.go:204\n                                                asm_amd64.s:1374\n        Error:          Expected nil, but got: \u0026errors.errorString{s:\"unable to get the weather forecast\"}\n        Messages:       []\n\n\ngoroutine 1 [running]:\ngithub.com/negrel/debuggo/pkg/assert.debuggoGen_Fail(0xc000018360, 0x52, 0xc00014bf38, 0x1, 0x1, 0xc000018360)\n        /home/negrel/code/golang/src/github.com/negrel/debuggo/pkg/assert/assertions.go:1071 +0x2a7\ngithub.com/negrel/debuggo/pkg/assert.debuggoGen_Nil(0x582c00, 0xc000012d90, 0xc00014bf38, 0x1, 0x1, 0x5e9260)\n        /home/negrel/code/golang/src/github.com/negrel/debuggo/pkg/assert/assertions.go:1179 +0xdb\ngithub.com/negrel/debuggo/pkg/assert.Nil(...)\n        /home/negrel/code/golang/src/github.com/negrel/debuggo/pkg/assert/assertions.go:353\nmain.main()\n        /home/negrel/code/golang/src/github.com/negrel/debuggo/examples/assert/main.go:15 +0xda\nexit status 2\n\n```\n\nOkay, assertions are great for debugging but logging can also be useful.\n\n## The `log` package\nThis package is a wrapper around the `log` package of the standard lib. There are 7 log levels, and you can choose one of \nthe following using a build tag:\n- Panic\n- Fatal\n- Error\n- Warn\n- Info\n- Debug\n- Trace\n\nEach log level have 4 method, for example the `info` level have the following:\n- Info(\"my message\")\n- Infoln(\"my message\")\n- Infof(\"My message is %v:\", \"hello world\")\n- Infofn(myfunction)\n\nTake a look at [examples/log/main.go](https://github.com/negrel/debuggo/blob/master/examples/log/main.go). By\ndefault, logs are disable.\n\n```bash\n# Let's run the example\n$ go run .\n\n# Nothing happend, let's try using the `info` build tag.\n$ go run -tags info .\n2020/10/24 10:19:59 [INFO] - Info log\n2020/10/24 10:19:59 [WARN] - Warning log\n2020/10/24 10:19:59 [ERROR] - Error log\n2020/10/24 10:19:59 [FATAL] - Fatal log\nexit status 1\n```\n\n## Analysing binaries\n\nIf you have taken a look at the generated code in pkg/* you must have notice that many functions are empty. Thus, we may\nask ourselves if there is an overhead to use Debuggo packages ?\n\n### Disassemble binaries\n\nTo answer this question, we should take a look at the produced binaries:\n```bash\n# Go to an example\n$ cd examples/log/\n\n# Let's build the example with the `info` build tag\n$ go build -tags info .\n\n# Let's disassemble the file.\n$ objdump log -d \u003e log_info.asm\n\n# Number of line\n$ wc -l log_info.asm\n182342 log_info.asm\n\n# Let's build the example without any build tag\n$ go build .\n\n# Let's disassemble the file.\n$ objdump log -d \u003e log.asm\n\n# Number of line\n$ wc -l log.asm\n149495 log.asm\n``` \n\nThere is a difference of **32847** lines between the two disassembled files. This show us that the produced binaries are\ndifferent but that's not enough to prove that all call to `log` have been removed.\n\n### Static Single Assignment (SSA)\n\nIn order to get a better understanding of the produced binaries we're going to analyse generated SSA:\n\n```bash\n# So, we're still in the examples/log directory\n# Let's generate the SSA with the `info` build tag \n$ GOSSAFUNC=main go build -tags info .\n\n# An ssa.html file have been generated\n$ mv ssa.html ssa_info.html\n\n# Let's generate the SSA without any build tag \n$ GOSSAFUNC=main go build .\n```\n\nNow tht we have two HTML files containing the compilation phases of our example, let's analyse them.\n\nLet's start with `ssa.html`:  \nSince we only care about the result, we should analyse the last phase (*genssa*):\n```\n# /home/negrel/code/golang/src/github.com/negrel/debuggo/examples/log/main.go\n00000 (7) TEXT \"\".main(SB), ABIInternal\n00001 (7) FUNCDATA $0, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)\n00002 (7) FUNCDATA $1, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)\nb22\n00003 (+15) RET\n00004 (?) END\n```\nThis is the expected result since without any build flag, the main function is empty.\n\nLet's compare with the `ssa_info.html`:\n```\n# /home/negrel/code/golang/src/github.com/negrel/debuggo/examples/log/main.go\n00000 (7) TEXT \"\".main(SB), ABIInternal\n...\n00014 (10) PCDATA $1, $0\nv70\n00015 (10) CALL github.com/negrel/debuggo/pkg/log.Infoln(SB)\nv120\n00016 (+11) XORPS X0, X0\n...\nv92\n00026 (11) CALL github.com/negrel/debuggo/pkg/log.Warnln(SB)\n...\n00037 (12) CALL github.com/negrel/debuggo/pkg/log.Errorln(SB)\n...\n00048 (13) CALL github.com/negrel/debuggo/pkg/log.Fatalln(SB)\n...\n# /home/negrel/code/golang/src/github.com/negrel/debuggo/pkg/log/exported.info.go\nv159\n00055 (+24) MOVQ github.com/negrel/debuggo/pkg/log.std(SB), AX\nv157\n...\nb19\n00065 (+24) RET\n00066 (?) END\n```\n\nThis result also match our expectations since we have call to `log` functions. You may have notice that only call to\nthe available functions at the `info` level are present.\n\n### Contributing\nIf you want to contribute to Debuggo to add a feature or improve the code contact me at\n[negrel.dev@protonmail.com](mailto:negrel.dev@protonmail.com), open an [issue](https://github.com/negrel/debuggo/issues)\nor make a [pull request](https://github.com/negrel/debuggo/pulls).\n\n## :stars: Show your support\nPlease give a :star: if this project helped you!\n\n#### :scroll: License\nMIT © [Alexandre Negrel](https://www.negrel.dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnegrel%2Fdebuggo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnegrel%2Fdebuggo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnegrel%2Fdebuggo/lists"}