From 8605d5cfe1043d41703ea8ca2604aace1d4d747c Mon Sep 17 00:00:00 2001 From: Paul Cristian Sarbu Date: Tue, 18 Jun 2024 16:09:13 +0200 Subject: proto tutorial: Add section on debugging This showcases that also generated proto headers will be staged for debugging. --- doc/tutorial/proto.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) (limited to 'doc/tutorial/proto.md') diff --git a/doc/tutorial/proto.md b/doc/tutorial/proto.md index e52f38d2..1eac9c13 100644 --- a/doc/tutorial/proto.md +++ b/doc/tutorial/proto.md @@ -404,7 +404,7 @@ $ Adding a test ------------- -Finally, let's add a test. As we use the `protobuf` repository as +Now, let's add a test. As we use the `protobuf` repository as workspace root, we add the test script ad hoc into a targets file, using the `"file_gen"` rule. For debugging a potentially failing test, we also keep the intermediate files the test generates. Add to the top-level @@ -546,3 +546,99 @@ Person ID: 12345 INFO: Target tainted ["test"]. $ ``` + +Debugging with generated files +------------------------------ + +Finally, let's look at how debugging using protobufs looks like. In the root +`TARGETS` file we can add a debug version of the `"list_people"` binary, +together with the target to stage its respective debug artifacts (as described +in the chapter on [*Debugging*](./hello-world.md)). + +``` {.jsonc srcname="TARGETS"} +... +, "list_people debug": + { "type": "configure" + , "target": "list_people" + , "config": + { "type": "let*" + , "bindings": [["DEBUG", true]] + , "body": {"type": "env", "vars": ["DEBUG"]} + } + } +, "list_people debug staged": + { "type": ["@", "rules", "CC", "install-with-deps"] + , "targets": ["list_people debug"] + } +... +``` + +The debugging target can then be installed to a directory of our choosing. + +``` sh +$ just-mr install "list_people debug staged" -o .ext/debug +INFO: Performing repositories setup +INFO: Found 23 repositories to set up +INFO: Setup finished, exec ["just","install","-C","...","list_people debug staged","-o",".ext/debug"] +INFO: Requested target is [["@","","","list_people debug staged"],{}] +INFO: Analysed target [["@","","","list_people debug staged"],{}] +INFO: Export targets found: 0 cached, 90 uncached, 0 not eligible for caching +INFO: Discovered 419 actions, 89 trees, 1 blobs +INFO: Building [["@","","","list_people debug staged"],{}]. +[...] +INFO: Processed 419 actions, 1 cache hits. +INFO: Artifacts can be found in: + /tmp/tutorial/.ext/debug/bin/list_people [2cc2f0efa28327bdf7d49f5d2cafcc25c1693a4c:41761464:x] + /tmp/tutorial/.ext/debug/include/absl/algorithm/algorithm.h [59aeed7d264d927e44648428056cc9c489fad844:2190:f] + /tmp/tutorial/.ext/debug/include/absl/algorithm/container.h [c7bafae1477cf2bb88928b92d0248cb8a146814c:78387:f] + ... + /tmp/tutorial/.ext/debug/include/absl/types/variant.h [ac93464bf8d0f63f745b8461daa7698a91caf6f7:34055:f] + /tmp/tutorial/.ext/debug/include/absl/utility/utility.h [fc0d1f65516a3da1341f639577acb4fdab64fe0d:8711:f] + /tmp/tutorial/.ext/debug/include/addressbook.pb.h [964e2745b22e5920f291801db91f2c73ed5435ad:44427:f] + /tmp/tutorial/.ext/debug/include/google/protobuf/any.h [03ddf3f54386e158b1f2575c158f1106d7265a24:5302:f] + /tmp/tutorial/.ext/debug/include/google/protobuf/any.pb.h [b9c4ada87b05a3fdeef134e561d4ce010040728e:15844:f] + /tmp/tutorial/.ext/debug/include/google/protobuf/any.proto [eff44e5099da27f7fb1ef14bb34902ccf4250b89:6154:f] + ... + /tmp/tutorial/.ext/debug/include/google/protobuf/wrappers.pb.h [02819d3219fe8ffcaf67cee25b7a73ab6e934f24:69964:f] + /tmp/tutorial/.ext/debug/include/google/protobuf/wrappers.proto [1959fa55a4e7f284a9d6a78a447c5d89d137e87c:4044:f] + /tmp/tutorial/.ext/debug/include/utf8_validity.h [4a8d75b3b46d569526b9ae36814e71f1dab476d7:692:f] + /tmp/tutorial/.ext/debug/include/zconf.h [fb76ffe312ae45cf5d5d5e448f81e06fa79ab874:16682:f] + /tmp/tutorial/.ext/debug/include/zlib.h [6b7244f9943219c7b6e5a08d4913f2a15810d0c4:96778:f] + /tmp/tutorial/.ext/debug/work/absl/algorithm/algorithm.h [59aeed7d264d927e44648428056cc9c489fad844:2190:f] + /tmp/tutorial/.ext/debug/work/absl/algorithm/container.h [c7bafae1477cf2bb88928b92d0248cb8a146814c:78387:f] + ... + /tmp/tutorial/.ext/debug/work/absl/types/span.h [88cd75954084d0df6d774fc038f243fdc1140942:27228:f] + /tmp/tutorial/.ext/debug/work/absl/types/variant.h [ac93464bf8d0f63f745b8461daa7698a91caf6f7:34055:f] + /tmp/tutorial/.ext/debug/work/absl/utility/utility.h [fc0d1f65516a3da1341f639577acb4fdab64fe0d:8711:f] + /tmp/tutorial/.ext/debug/work/addressbook.pb.cc [b19ba7ad01dbf9c701f58b2b511845da2f0e8171:36687:f] + /tmp/tutorial/.ext/debug/work/addressbook.pb.h [964e2745b22e5920f291801db91f2c73ed5435ad:44427:f] + ... + /tmp/tutorial/.ext/debug/work/google/protobuf/any.h [03ddf3f54386e158b1f2575c158f1106d7265a24:5302:f] + /tmp/tutorial/.ext/debug/work/google/protobuf/any.pb.h [b9c4ada87b05a3fdeef134e561d4ce010040728e:15844:f] + /tmp/tutorial/.ext/debug/work/google/protobuf/any.proto [eff44e5099da27f7fb1ef14bb34902ccf4250b89:6154:f] + ... + /tmp/tutorial/.ext/debug/work/list_people.cc [b309c596804739007510f06ff62c12898275fec7:2268:f] + ... + /tmp/tutorial/.ext/debug/work/zlib.h [6b7244f9943219c7b6e5a08d4913f2a15810d0c4:96778:f] + /tmp/tutorial/.ext/debug/work/zutil.c [b1c5d2d3c6daf5a4b7a337dafe3e862ca177b41c:7179:f] + /tmp/tutorial/.ext/debug/work/zutil.h [902a304cc2d913d5548e0489c0c451790208c96f:7247:f] +INFO: Backing up artifacts of 90 export targets +``` + +As the command requires (re)building many targets in debug mode, some of the +resulting output was replaced with `"..."` for brevity. +What needs to be noted here is that for each (directly or transitively) +included proto file the corresponding _generated_ `.pb.h` header file and +`.pb.cc` source file get staged as well, ensuring that also all needed proto +symbols will be available to a debugger. + +In order to debug now this binary, one can, for example, use the +`addressbook.data` file generated by the previous test, staged accordingly, as +input database for the `list_people` binary. + +``` sh +$ just-mr install test -o .ext/test_data +[...] +$ cd .ext/debug +$ gdb --args bin/list_people ../test_data/work/addressbook.data +``` -- cgit v1.2.3