diff options
Diffstat (limited to 'doc/tutorial')
| -rw-r--r-- | doc/tutorial/getting-started.md | 163 | ||||
| -rw-r--r-- | doc/tutorial/hello-world.md | 49 |
2 files changed, 212 insertions, 0 deletions
diff --git a/doc/tutorial/getting-started.md b/doc/tutorial/getting-started.md index 4d64157b..a97aea60 100644 --- a/doc/tutorial/getting-started.md +++ b/doc/tutorial/getting-started.md @@ -225,3 +225,166 @@ INFO: Artifacts built, logical paths are: upper.txt [83cf24cdfb4891a36bee93421930dd220766299a:6:f] $ ``` + +Inspecting internals: Analyse +----------------------------- + +For our simple targets, it is easy to remember what they look like, +and what the build steps are. For more complex projects this might +no longer be the case. Therefore, *justbuild* tries to be very +transparent about its understanding of the build. The command +to do so is called `analyse` and also takes a target as argument. +It shows all(!) the information available to a target depending +on it. In the case of `greeter` this is just a single artifact. + +``` sh +$ just analyse greeter +INFO: Requested target is [["@","","","greeter"],{}] +INFO: Analysed target [["@","","","greeter"],{}] +INFO: Result of target [["@","","","greeter"],{}]: { + "artifacts": { + "out.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"} + }, + "provides": { + }, + "runfiles": { + } + } +INFO: Target tainted ["test"]. +``` + +As we can see, the artifact will be installed at the logical +path `out.txt`. The artifact itself is generated by a build +action, more precisely, it is the output `out.txt` of that +action. Actions, in general, can have more than one output. + +For the target `both` we find the same artifact at a different +output location in this case `hello.txt`. + +``` sh +$ just analyse both +INFO: Requested target is [["@","","","both"],{}] +INFO: Analysed target [["@","","","both"],{}] +INFO: Result of target [["@","","","both"],{}]: { + "artifacts": { + "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"}, + "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"} + }, + "provides": { + }, + "runfiles": { + "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"}, + "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"} + } + } +INFO: Target tainted ["test"]. +``` + +We also see another technical detail. As an `install` target, +`both` also has the same artifact in the `runfiles` arrangement of +files. Having two dedicated arrangements of artifacts, that are both +installed when the target is installed, can be useful to distinguish +between the main artifact and files needed when building against +that target (e.g., to distinguish a library from its header files). +As a very generic built-in rule, however, `install` simply makes +all files available in both arrangements. + +The canonical way to obtain all action definitions is to dump the +action graph using the `--dump-graph` option. + +``` sh +$ just analyse both --dump-graph all-actions.json +$ cat all-actions.json +``` + +As we know that the action was generated by the `greeter` target, +was can also ask that target for the actions associated with it +using the `--dump-actions` option. The `install` target does not +generate any actions. + +``` sh +$ just analyse greeter --dump-actions - +INFO: Requested target is [["@","","","greeter"],{}] +INFO: Analysed target [["@","","","greeter"],{}] +INFO: Result of target [["@","","","greeter"],{}]: { + "artifacts": { + "out.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"} + }, + "provides": { + }, + "runfiles": { + } + } +INFO: Actions for target [["@","","","greeter"],{}]: +[ + { + "command": ["sh","-c","echo -n 'Hello ' > out.txt\ncat name.txt >> out.txt\n"], + "input": { + "name.txt": { + "data": { + "path": "name.txt", + "repository": "" + }, + "type": "LOCAL" + } + }, + "output": ["out.txt"] + } +] +$ just analyse both --dump-actions - +INFO: Requested target is [["@","","","both"],{}] +INFO: Analysed target [["@","","","both"],{}] +INFO: Result of target [["@","","","both"],{}]: { + "artifacts": { + "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"}, + "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"} + }, + "provides": { + }, + "runfiles": { + "hello.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"}, + "upper.txt": {"data":{"id":"f122c2af488a56c94d08650a9d799dbb910484409116b8e0c071e198082256ef","path":"out.txt"},"type":"ACTION"} + } + } +INFO: Actions for target [["@","","","both"],{}]: +[ +] +$ +``` + +However, those actions are not owned by a target in any way. +Actions are identified by their definition in the same way as +`git` identifies a blob by its sequence of bytes and names it by +a suitable hash value. So, let's add another target defining an +action in the same way. + +``` {.jsonc srcname="TARGETS"} +... +, "another greeter": + { "type": "generic" + , "cmds": ["echo -n 'Hello ' > out.txt", "cat name.txt >> out.txt"] + , "outs": ["out.txt"] + , "deps": ["name.txt"] + } +... +``` + +Then we find that it defines the same artifact. + +``` sh +$ just analyse 'another greeter' +INFO: Requested target is [["@","","","another greeter"],{}] +INFO: Analysed target [["@","","","another greeter"],{}] +INFO: Result of target [["@","","","another greeter"],{}]: { + "artifacts": { + "out.txt": {"data":{"id":"28c9f5feb17361a5f755b19961b4c80c651586269786d93e58bfff5b0038c620","path":"out.txt"},"type":"ACTION"} + }, + "provides": { + }, + "runfiles": { + } + } +``` + +This is also the notion of equality used to detect conflicts when +analysing targets before running any actions. diff --git a/doc/tutorial/hello-world.md b/doc/tutorial/hello-world.md index b700252d..afd8629f 100644 --- a/doc/tutorial/hello-world.md +++ b/doc/tutorial/hello-world.md @@ -422,3 +422,52 @@ INFO: Artifacts built, logical paths are: (1 runfiles omitted.) $ ``` + +The ommitted (i.e., not shown but still built) runfile is the header file. As +mentioned in the introduction to `just analyse` this is a typical use of that +second artifact arrangement. We can also have a look at the other information +that library provides. + +``` sh +$ just-mr analyse greet greet +INFO: Performing repositories setup +INFO: Found 3 repositories to set up +INFO: Setup finished, exec ["just","analyse","-C","...","greet","greet"] +INFO: Requested target is [["@","tutorial","greet","greet"],{}] +INFO: Analysed target [["@","tutorial","greet","greet"],{}] +INFO: Result of target [["@","tutorial","greet","greet"],{}]: { + "artifacts": { + "greet/libgreet.a": {"data":{"id":"c4ba32e2fc1ce267b4245d8885ae7b53405d41a709f853061549ca93aa73a6ac","path":"work/greet/libgreet.a"},"type":"ACTION"} + }, + "provides": { + "compile-args": [ + ], + "compile-deps": { + }, + "debug-hdrs": { + }, + "debug-srcs": { + }, + "link-args": [ + "greet/libgreet.a" + ], + "link-deps": { + }, + "lint": [ + ], + "package": { + "cflags-files": {}, + "ldflags-files": {}, + "name": "greet" + }, + "run-libs": { + }, + "run-libs-args": [ + ] + }, + "runfiles": { + "greet/greet.hpp": {"data":{"path":"greet/greet.hpp","repository":"tutorial"},"type":"LOCAL"} + } + } +$ +``` |