diff options
| -rw-r--r-- | doc/tutorial/getting-started.org | 4 | ||||
| -rw-r--r-- | doc/tutorial/proto.org | 198 |
2 files changed, 103 insertions, 99 deletions
diff --git a/doc/tutorial/getting-started.org b/doc/tutorial/getting-started.org index 3dc48511..5a041397 100644 --- a/doc/tutorial/getting-started.org +++ b/doc/tutorial/getting-started.org @@ -1,7 +1,7 @@ * Getting Started -In order to use /justbuild/, first make sure that ~just~ and ~just-mr~ are -available in your ~PATH~. +In order to use /justbuild/, first make sure that ~just~, ~just-mr~, and +~just-import-git~ are available in your ~PATH~. ** Creating a new project diff --git a/doc/tutorial/proto.org b/doc/tutorial/proto.org index 5405edac..d9600594 100644 --- a/doc/tutorial/proto.org +++ b/doc/tutorial/proto.org @@ -8,48 +8,65 @@ itself; rather, it is assumed that the reader has some knowledge on ** Setting up the repository configuration +Before we begin, we first need to declare where the root of our workspace is +located by creating the empty file ~ROOT~: + +#+BEGIN_SRC sh +$ touch ROOT +#+END_SRC + The ~protobuf~ repository conveniently contains an [[https://github.com/protocolbuffers/protobuf/tree/v3.12.4/examples][example]], so we can use this and just add our own target files. We create -file ~repos.json~ as follows. +file ~repos.template.json~ as follows. +#+SRCNAME: repos.template.json #+BEGIN_SRC js { "repositories": { "": - { "repository": "protobuf" + { "repository": + { "type": "zip" + , "content": "7af7165b585e4aed714555a747b6822376176ef4" + , "fetch": "https://github.com/protocolbuffers/protobuf/archive/refs/tags/v3.12.4.zip" + , "subdir": "protobuf-3.12.4/examples" + } , "target_root": "tutorial" - , "bindings": {"rules": "just/rules-just"} + , "bindings": {"rules": "rules-cc"} } , "tutorial": {"repository": {"type": "file", "path": "."}} - , ... } } #+END_SRC -The remaining entries are just the ones from ~etc/repos.json~ from -the /justbuild/ repository, for ease of reading prefixed with ~just/~; -here we keep in mind that we're now working -in a different location, and hence have to replace the relative paths -by appropriate absolute ones. In fact, that configuration can also be -created from the above template by using the ~bin/just-import-git.py~ -script, with option ~--as just~. +The missing entry ~"rules-cc"~ refers to our C/C++ build rules provided +[[https://github.com/just-buildsystem/rules-cc][online]]. These rules support +protobuf if the dependency ~"protoc"~ is provided. To import this rule +repository including the required transitive dependencies for protobuf, the +~bin/just-import-git~ script with option ~--as rules-cc~ can be used to +generate the actual ~repos.json~: -To build the example with ~just~, the only task is to write a targets -file at ~examples/TARGETS~. As that contains a couple of new concepts, -we will do this step by step. +#+BEGIN_SRC sh +$ just-import-git -C repos.template.json -b master --as rules-cc https://github.com/just-buildsystem/rules-cc > repos.json +#+END_SRC + +To build the example with ~just~, the only task is to write targets files. As +that contains a couple of new concepts, we will do this step by step. ** The proto library First, we have to declare the proto library. In this case, it only -contains one file and has no dependencies. +contains the file ~addressbook.proto~ and has no dependencies. To +declare the library, create a ~TARGETS~ file with the following +content: +#+SRCNAME: TARGETS #+BEGIN_SRC js { "address": { "type": ["@", "rules", "proto", "library"] , "name": ["addressbook"] , "srcs": ["addressbook.proto"] } -... +} #+END_SRC In general, proto libraries could also depend on other proto libraries; @@ -58,12 +75,12 @@ those would be added to the ~"deps"~ field. When building the library, there's very little to do. #+BEGIN_SRC sh -$ just-mr build examples address -INFO: Requested target is [["@","","examples","address"],{}] -INFO: Analysed target [["@","","examples","address"],{}] +$ just-mr build address +INFO: Requested target is [["@","","","address"],{}] +INFO: Analysed target [["@","","","address"],{}] INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching INFO: Discovered 0 actions, 0 trees, 0 blobs -INFO: Building [["@","","examples","address"],{}]. +INFO: Building [["@","","","address"],{}]. INFO: Processed 0 actions, 0 cache hits. INFO: Artifacts built, logical paths are: $ @@ -81,9 +98,9 @@ and did not even construct the dependency graph for that target. A proto library simply provides the dependency structure of the ~.proto~ files. #+BEGIN_SRC sh -$ just-mr analyse --dump-nodes - examples address -INFO: Requested target is [["@","","examples","address"],{}] -INFO: Result of target [["@","","examples","address"],{}]: { +$ just-mr analyse --dump-nodes - address +INFO: Requested target is [["@","","","address"],{}] +INFO: Result of target [["@","","","address"],{}]: { "artifacts": { }, "provides": { @@ -94,7 +111,7 @@ INFO: Result of target [["@","","examples","address"],{}]: { "runfiles": { } } -INFO: Target nodes of target [["@","","examples","address"],{}]: +INFO: Target nodes of target [["@","","","address"],{}]: { "089f6cae7ca77bb786578d3e0138b6ff445c5c92": { "result": { @@ -157,6 +174,7 @@ abstract names. Fortunately, our ~CC~ rules are aware of proto libraries, so we can simply use them. Our target file hence continues as follows. +#+SRCNAME: TARGETS #+BEGIN_SRC js ... , "add_person": @@ -180,17 +198,17 @@ a bit of time, as the proto compiler has to be built. But in follow-up builds, also in different projects, the target-level cache is filled already. #+BEGIN_SRC sh -$ just-mr build examples add_person +$ just-mr build add_person ... -$ just-mr build examples add_person -INFO: Requested target is [["@","","examples","add_person"],{}] -INFO: Analysed target [["@","","examples","add_person"],{}] +$ just-mr build add_person +INFO: Requested target is [["@","","","add_person"],{}] +INFO: Analysed target [["@","","","add_person"],{}] INFO: Export targets found: 3 cached, 0 uncached, 0 not eligible for caching INFO: Discovered 5 actions, 2 trees, 0 blobs -INFO: Building [["@","","examples","add_person"],{}]. +INFO: Building [["@","","","add_person"],{}]. INFO: Processed 5 actions, 5 cache hits. INFO: Artifacts built, logical paths are: - add_person [a76fb26b48dc9a5523ecfffd0c139b3a7466c84d:1862512:x] + add_person [bcbb3deabfe0d77e6d3ea35615336a2f59a1b0aa:2285928:x] $ #+END_SRC @@ -198,38 +216,36 @@ If we look at the actions associated with the binary, we find that those are still the two actions we expect: a compile action and a link action. #+BEGIN_SRC sh -$ just-mr analyse examples add_person --dump-actions - -INFO: Requested target is [["@","","examples","add_person"],{}] -INFO: Result of target [["@","","examples","add_person"],{}]: { +$ just-mr analyse add_person --dump-actions - +INFO: Requested target is [["@","","","add_person"],{}] +INFO: Result of target [["@","","","add_person"],{}]: { "artifacts": { - "add_person": {"data":{"id":"3cfc3fca335a722ab55b017ecdd4d465a0eb700c","path":"add_person"},"type":"ACTION"} + "add_person": {"data":{"id":"fcf211e2291b2867375e915538ce04cb4dfae86d","path":"add_person"},"type":"ACTION"} }, "provides": { }, "runfiles": { } } -INFO: Actions for target [["@","","examples","add_person"],{}]: +INFO: Actions for target [["@","","","add_person"],{}]: [ { - "command": ["c++","-O2","-DNDEBUG","-std=c++20","-Wall","-Wextra","-Wpedantic","-Wsign-conversion","-Werror","-pedantic-errors","-I","work","-isystem","include","-c","work/add_person.cc","-o","work/add_person.o"], + "command": ["c++","-I","work","-isystem","include","-c","work/add_person.cc","-o","work/add_person.o"], "env": { - "PATH": "/bin:/sbin:/usr/bin:/usr/sbin" + "PATH": "/bin:/usr/bin" }, "input": { ... - } }, "output": ["work/add_person.o"] }, { - "command": ["c++","-o","add_person","-O2","-DNDEBUG","-std=c++20","-Wall","-Wextra","-Wpedantic","-Wsign-conversion","-Werror","-pedantic-errors","add_person.o","libaddressbook.a","libprotobuf.a","libprotobuf_lite.a","libzlib.a"], + "command": ["c++","-o","add_person","add_person.o","libaddressbook.a","libprotobuf.a","libprotobuf_lite.a","libzlib.a"], "env": { - "PATH": "/bin:/sbin:/usr/bin:/usr/sbin" + "PATH": "/bin:/usr/bin" }, "input": { ... - } }, "output": ["add_person"] } @@ -246,11 +262,11 @@ still analysed. In the one anonymous target, we find again the abstract node we discussed earlier. #+BEGIN_SRC sh -$ just-mr analyse examples add_person --dump-targets - -INFO: Requested target is [["@","","examples","add_person"],{}] -INFO: Result of target [["@","","examples","add_person"],{}]: { +$ just-mr analyse add_person --dump-targets - +INFO: Requested target is [["@","","","add_person"],{}] +INFO: Result of target [["@","","","add_person"],{}]: { "artifacts": { - "add_person": {"data":{"id":"3cfc3fca335a722ab55b017ecdd4d465a0eb700c","path":"add_person"},"type":"ACTION"} + "add_person": {"data":{"id":"fcf211e2291b2867375e915538ce04cb4dfae86d","path":"add_person"},"type":"ACTION"} }, "provides": { }, @@ -260,35 +276,28 @@ INFO: Result of target [["@","","examples","add_person"],{}]: { INFO: List of analysed targets: { "#": { - "68da80fb6609eb6a402649daddadffc02c6eff04": { + "eda46ea21de25033ff7250e6a4cdc0b2c24be0c7": { "2a483a2de7f25c1bc066e47245f55ec9a2d4a719": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}] } }, "@": { "": { - "examples": { + "": { "add_person": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}], "address": [{}] } }, - "just/protobuf": { + "rules-cc": { + "CC": { + "defaults": [{}] + } + }, + "rules-cc/just/protobuf": { "": { "C++ runtime": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}], "protoc": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}], "well_known_protos": [{}] } - }, - "just/rules": { - "CC": { - "defaults": [{"ARCH":null,"COMPILER_FAMILY":null,"DEBUG":null,"OS":null}], - "toolchain": [{"ARCH":null,"COMPILER_FAMILY":null,"OS":null}], - "unknown": [{}] - } - }, - "just/rules-just": { - "CC": { - "defaults": [{"ARCH":null,"COMPILER_FAMILY":null,"DEBUG":null,"OS":null}] - } } } } @@ -304,10 +313,12 @@ target and then simply reflecting the values of that target. ** Adding a test Finally, let's add a test. As we use the ~protobuf~ repository as -workspace root, we add the test script ad hoc into the targets file, +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. +Create a top-level ~TARGETS~ file with the following content: +#+SRCNAME: TARGETS #+BEGIN_SRC js ... , "test.sh": @@ -331,7 +342,7 @@ test, we also keep the intermediate files the test generates. , "deps": ["add_person", "list_people"] , "keep": ["addressbook.data", "out.txt"] } -} +... #+END_SRC That example also shows why it is important that the generation @@ -343,34 +354,34 @@ the expected additional targets and the one anonymous target is reused by both binaries. #+BEGIN_SRC sh -$ just-mr analyse examples test --dump-targets - -INFO: Requested target is [["@","","examples","test"],{}] -INFO: Result of target [["@","","examples","test"],{}]: { +$ just-mr analyse test --dump-targets - +INFO: Requested target is [["@","","","test"],{}] +INFO: Result of target [["@","","","test"],{}]: { "artifacts": { - "result": {"data":{"id":"3196bca2b927fb1973546df8d69d64a9d47ff04b","path":"result"},"type":"ACTION"}, - "stderr": {"data":{"id":"3196bca2b927fb1973546df8d69d64a9d47ff04b","path":"stderr"},"type":"ACTION"}, - "stdout": {"data":{"id":"3196bca2b927fb1973546df8d69d64a9d47ff04b","path":"stdout"},"type":"ACTION"}, - "time-start": {"data":{"id":"3196bca2b927fb1973546df8d69d64a9d47ff04b","path":"time-start"},"type":"ACTION"}, - "time-stop": {"data":{"id":"3196bca2b927fb1973546df8d69d64a9d47ff04b","path":"time-stop"},"type":"ACTION"}, - "work/addressbook.data": {"data":{"id":"3196bca2b927fb1973546df8d69d64a9d47ff04b","path":"work/addressbook.data"},"type":"ACTION"}, - "work/out.txt": {"data":{"id":"3196bca2b927fb1973546df8d69d64a9d47ff04b","path":"work/out.txt"},"type":"ACTION"} + "result": {"data":{"id":"20967787c42a289f5598249e696f851dde50065c","path":"result"},"type":"ACTION"}, + "stderr": {"data":{"id":"20967787c42a289f5598249e696f851dde50065c","path":"stderr"},"type":"ACTION"}, + "stdout": {"data":{"id":"20967787c42a289f5598249e696f851dde50065c","path":"stdout"},"type":"ACTION"}, + "time-start": {"data":{"id":"20967787c42a289f5598249e696f851dde50065c","path":"time-start"},"type":"ACTION"}, + "time-stop": {"data":{"id":"20967787c42a289f5598249e696f851dde50065c","path":"time-stop"},"type":"ACTION"}, + "work/addressbook.data": {"data":{"id":"20967787c42a289f5598249e696f851dde50065c","path":"work/addressbook.data"},"type":"ACTION"}, + "work/out.txt": {"data":{"id":"20967787c42a289f5598249e696f851dde50065c","path":"work/out.txt"},"type":"ACTION"} }, "provides": { }, "runfiles": { - "read-write-test": {"data":{"id":"21c55e163e50cd6d7b52d936940ab493f51c4728"},"type":"TREE"} + "read-write-test": {"data":{"id":"c9d7bfc5bc8448bfef25b4e73e4494560bf6c350"},"type":"TREE"} } } INFO: List of analysed targets: { "#": { - "68da80fb6609eb6a402649daddadffc02c6eff04": { + "eda46ea21de25033ff7250e6a4cdc0b2c24be0c7": { "2a483a2de7f25c1bc066e47245f55ec9a2d4a719": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}] } }, "@": { "": { - "examples": { + "": { "add_person": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}], "address": [{}], "list_people": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}], @@ -378,24 +389,17 @@ INFO: List of analysed targets: "test.sh": [{}] } }, - "just/protobuf": { + "rules-cc": { + "CC": { + "defaults": [{}] + } + }, + "rules-cc/just/protobuf": { "": { "C++ runtime": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}], "protoc": [{"ADD_CFLAGS":null,"ADD_CXXFLAGS":null,"AR":null,"ARCH":null,"CC":null,"CFLAGS":null,"COMPILER_FAMILY":null,"CXX":null,"CXXFLAGS":null,"DEBUG":null,"ENV":null,"HOST_ARCH":null,"OS":null,"TARGET_ARCH":null}], "well_known_protos": [{}] } - }, - "just/rules": { - "CC": { - "defaults": [{"ARCH":null,"COMPILER_FAMILY":null,"DEBUG":null,"OS":null}], - "toolchain": [{"ARCH":null,"COMPILER_FAMILY":null,"OS":null}], - "unknown": [{}] - } - }, - "just/rules-just": { - "CC": { - "defaults": [{"ARCH":null,"COMPILER_FAMILY":null,"DEBUG":null,"OS":null}] - } } } } @@ -406,27 +410,27 @@ $ Finally, the test passes and the output is as expected. #+BEGIN_SRC sh -$ just-mr build examples test -Pwork/out.txt -INFO: Requested target is [["@","","examples","test"],{}] -INFO: Analysed target [["@","","examples","test"],{}] +$ just-mr build test -Pwork/out.txt +INFO: Requested target is [["@","","","test"],{}] +INFO: Analysed target [["@","","","test"],{}] INFO: Export targets found: 3 cached, 0 uncached, 0 not eligible for caching INFO: Target tainted ["test"]. INFO: Discovered 8 actions, 4 trees, 1 blobs -INFO: Building [["@","","examples","test"],{}]. +INFO: Building [["@","","","test"],{}]. INFO: Processed 8 actions, 5 cache hits. INFO: Artifacts built, logical paths are: result [7ef22e9a431ad0272713b71fdc8794016c8ef12f:5:f] stderr [e69de29bb2d1d6434b8b29ae775ad8c2e48c5391:0:f] stdout [7fab9dd1ee66a1e76a3697a27524f905600afbd0:196:f] - time-start [3e440f9ce86274043e2c18cbc769bd8e026f8512:11:f] - time-stop [3e440f9ce86274043e2c18cbc769bd8e026f8512:11:f] - work/addressbook.data [ae5c96711188769917a3af906d7cfbfc25645a28:41:f] - work/out.txt [0017cd9e728764f62870cb7db84ef42de913cdc3:101:f] + time-start [7ac216a2a98b7739ae5304d96cdfa6f0b0ed87b6:11:f] + time-stop [7ac216a2a98b7739ae5304d96cdfa6f0b0ed87b6:11:f] + work/addressbook.data [baa6f28731ff6d93fbef9fcc5f7e8ae900da5ba5:41:f] + work/out.txt [7fb178dd66ecf24fdb786a0f96ae5969b55442da:101:f] (1 runfiles omitted.) Person ID: 12345 Name: John Doe E-mail address: jdoe@example.org - Updated: 2022-12-12T09:58:07Z + Updated: 2022-12-14T18:08:36Z INFO: Target tainted ["test"]. $ #+END_SRC |