Merge pull request #4 from oreiche/stable-1.1

Release 1.1.1

CHANGELOG.md

@@ -1,7 +1,20 @@
-## Release `1.1.1` (UNRELEASED)
+## Release `1.1.1` (2023-06-02)
 
 Bug fixes on top of release `1.1.0`.
 
+### Fixes
+
+- Removed potential uses of `malloc` between `fork` and `exec`.
+  This removes the risk of deadlocks on certain combinations of
+  `C++` standard library and `libc`.
+- The link flags for the final linking now can be set via the
+  configuration variable `FINAL_LDFLAGS`; in particular, the stack
+  size can easily be adapted. The default stack size is now set to
+  8M, removing an overflow on systems where the default stack size
+  was significantly lower.
+- The man pages are now provided as markdown files, allowing to
+  potentially reduce the build dependencies to more standard ones.
+
 ## Release `1.1.0` (2023-05-19)
 
 A feature release on top of `1.0.0`, backwards compatible.

INSTALL.md

@@ -22,7 +22,7 @@ specify `arm64` as the target architecture via the `-D` flag:
 just-mr build -D '{"TARGET_ARCH":"arm64"}'
 ```
 
-The following table descries the most important supported configuration
+The following table describes the most important supported configuration
 variables. The full list can be obtained via `just-mr describe`.
 
 |Variable|Supported Values|Default Value for `just`|
@@ -35,6 +35,10 @@ variables. The full list can be obtained via `just-mr describe`.
 | DEBUG | true, false | false |
 | BUILD_STATIC_BINARY | true, false | false |
 
+Note that you can choose a different stack size for resulting binaries by
+adding `"-Wl,-z,stack-size=<size-in-bytes>"` to variable `"FINAL_LDFLAGS"`
+(which has to be a list of strings).
+
 ## Bootstrapping `just`
 
 It is also possible to build `just` without having an older binary,

TARGETS

@@ -8,6 +8,7 @@
     , "AR"
     , "ARCH"
     , "BUILD_STATIC_BINARY"
+    , "FINAL_LDFLAGS"
     , "CC"
     , "COMPILER_FAMILY"
     , "CXX"
@@ -45,6 +46,7 @@
     , "BUILD_STATIC_BINARY":
       [ "Boolean, default false. If set, try to build a (mainly) static binary."
       ]
+    , "FINAL_LDFLAGS": ["Compiler flags for linking the final binary."]
     , "DEBUG": ["Boolean, default false. Whether to build a debug version."]
     , "OS":
       [ "Operating system to build for."
@@ -82,6 +84,7 @@
     , "AR"
     , "ENV"
     , "BUILD_STATIC_BINARY"
+    , "FINAL_LDFLAGS"
     , "SOURCE_DATE_EPOCH"
     , "VERSION_EXTRA_SUFFIX"
     , "PKG_CONFIG_ARGS"
@@ -137,6 +140,7 @@
     , "AR"
     , "ENV"
     , "BUILD_STATIC_BINARY"
+    , "FINAL_LDFLAGS"
     , "SOURCE_DATE_EPOCH"
     , "VERSION_EXTRA_SUFFIX"
     ]

bin/bootstrap.py

@@ -85,6 +85,7 @@
 CXX="c++"
 CFLAGS = []
 CXXFLAGS = []
+FINAL_LDFLAGS = ["-Wl,-z,stack-size=8388608"]
 
 if "COMPILER_FAMILY" in CONF:
     if CONF["COMPILER_FAMILY"] == "gnu":
@@ -104,6 +105,8 @@
     CFLAGS=CONF["ADD_CFLAGS"]
 if "ADD_CXXFLAGS" in CONF:
     CXXFLAGS=CONF["ADD_CXXFLAGS"]
+if "FINAL_LDFLAGS" in CONF:
+    FINAL_LDFLAGS+=CONF["FINAL_LDFLAGS"]
 
 BOOTSTRAP_CC = [CXX] + CXXFLAGS + ["-std=c++20", "-DBOOTSTRAP_BUILD_TOOL"]
 
@@ -371,8 +374,8 @@ def bootstrap():
             cmd = BOOTSTRAP_CC + flags + ["-c", f, "-o", obj_file_name]
             ts.submit(run, cmd, cwd=src_wrkdir)
     bootstrap_just = os.path.join(WRKDIR, "bootstrap-just")
-    cmd = BOOTSTRAP_CC + ["-o", bootstrap_just
-                          ] + object_files + dep_flags["link"]
+    cmd = BOOTSTRAP_CC + FINAL_LDFLAGS + ["-o", bootstrap_just
+                                          ] + object_files + dep_flags["link"]
     run(cmd, cwd=src_wrkdir)
     CONF_FILE = os.path.join(WRKDIR, "repo-conf.json")
     LOCAL_ROOT = os.path.join(WRKDIR, ".just")

share/man/just-graph-file.5.md

@@ -0,0 +1,152 @@
+% JUST GRAPH FILE(5) | File Formats Manual
+
+NAME
+====
+
+just graph file -- The format of the action graph used by **just(1)**
+
+DESCRIPTION
+===========
+
+The file is read as JSON. Any other serialization describing the same
+JSON object is equivalent. We assume, that in JSON objects, each key
+occurs at most once; it is implementation defined how repetitions of the
+same key are treated.
+
+Artifacts and their serialization
+---------------------------------
+
+There are four different kind of artifacts. The serialization of the
+artifact is always a JSON object with two keys: `"type"` and `"data"`.
+The value for `"type"` is always on of the strings `"LOCAL"`, `"KNOWN"`,
+`"ACTION"`, or `"TREE"`. The value for `"data"` is a JSON object with
+keys depending on which type the artifact is of.
+
+ - `"LOCAL"` artifacts refer to source files in a logical repository.
+   The describing data are
+    - the `"repository"`, given as its global name, and
+    - the `"path"`, given as path relative to the root of that
+      repository.
+ - `"KNOWN"` artifacts are described by the hash of their content. The
+   describing data are
+    - the `"file_type"`, which is a one-letter string,
+       - `"f"` for regular, non-executable files,
+       - `"x"` for executable files, or
+       - `"t"` for trees.
+    - the `"id"` specifying the (applicable) hash of the file given as
+      its hexadecimal encoding, a string, and
+    - the `"size"` of the artifact, a number, in bytes.
+ - `"ACTION"` artifacts are the outputs of actions. The defining data
+   are
+    - the `"id"`, a string with the name of the action, and
+    - the `"path"`, specifying the path of this output artifact,
+      relative to the root of the action directory
+ - `"TREE"` artifacts refer to trees defined in the action graph. The
+   defining data are
+    - the `"id"`, a string with the name of the tree.
+
+Actions and their serialization
+-------------------------------
+
+Actions are given by the data described in the following sections. For
+each item a key is associated and the serialization of the action is a
+JSON object mapping those keys to the respective serialization of the
+values. For some data items default values are given; if the value for
+the respective item equals the default, the respective key-value pair
+may be omitted in the serialization.
+
+ - `"command"` specifies the command to be executed. It is a non-empty
+   list of strings that forms the argument vector; the first entry is
+   taken as program. This key is mandatory.
+
+ - `"env"` specifies the environment variables the command should be
+   executed with. It is given as map from strings to strings. The
+   default is the empty map.
+
+ - `"input"` describes the files available to the action. The action
+   must not modify them in any way. They are specified as map from
+   paths to artifacts (the latter serialized as described). Paths have
+   to be relative paths and are taken relative to the working directory
+   of the action. The default is the empty map.
+
+ - `"output"` describes the files the action is supposed to generate,
+   if any. It is given as a list of strings, each specifying a file
+   name by a path relative to the working directory of the action. The
+   default is the empty list. However, every action has to produce some
+   form of output, so if `"output"` is empty, `"output_dirs"` cannot be
+   empty.
+
+ - `"output_dirs"` describes the directory output of the action, if
+   any. It is given as a list of strings, each specifying the a
+   directory name by a path relative to the working directory of the
+   action. The `"output_dirs"` may also specify directories from which
+   individual files are specified as `"output"`. The default value for
+   `"output_dirs"` is the empty list. However, every action to produce
+   some form of output, so if `"output_dirs"` is empty, `"output"`
+   cannot be empty.
+
+ - `"may_fail"` can either be `null` or a string. If it is a string,
+   the build should be continued, even if that action returns a
+   non-zero exit state. If the action returns a non-zero exit code,
+   that string should be shown to the user in a suitable way (e.g.,
+   printing on the console). Otherwise (i.e., if no `"may_fail"` string
+   is given), the build should be aborted if the action returns a
+   non-zero exit code. The default for `"may_fail"` is `null`, i.e.,
+   abort on non-zero exit code.
+
+ - `"no_cache"` is a boolean. If `true`, the action should never be
+   cached, not even on success. The default is `false`.
+
+The graph format
+----------------
+
+The action graph is given by a JSON object.
+
+ - The value for the key `"blobs"` is a list of strings. Those strings
+   should be considered known; they might (additionally to what was
+   agreed ahead of time as known) referred to as `"KNOWN"` artifacts.
+
+ - The value for the key `"trees"` is a JSON object, mapping the names
+   of trees to their definition. The definition of a tree is JSON
+   object mapping paths to artifacts (serialized in the way described
+   earlier). The paths are always interpreted as relative paths,
+   relative to the root of the tree. It is not a requirement that a new
+   tree is defined for every subdirectory; if a path contains the
+   hierarchy separator, which is slash, then implicitly a subdirectory
+   is present, and all path going through that subdirectory contribute
+   to its content. It is, however, an error, if the a path is a prefix
+   of another one (with the comparison done in the canonical form of
+   that path).
+
+ - The value for the key `"actions"` is a JSON object, mapping names of
+   actions to their respective definition (serialized as JSON).
+
+Additional keys
+---------------
+
+Any JSON object described here might have additional keys on top of the
+ones described. Implementations reading the graph have to accept and
+ignore those. Implementations writing action-graph files should be aware
+that a future version of this file format might give a specific meaning
+to those extra keys.
+
+Graphs written by **just(1)** have the additional key `"origins"` in
+each action. The value is a list of all places where this action was
+requested (so often, but not always, the list has length 1). Each such
+place is described by a JSON object with the following keys.
+
+ - `"target"` The target in which the action was requested. It is given
+   as a list, either a full qualified named target given as `"@"`
+   followed by global repository name, module, and target name, or an
+   anonymous target, given by `"#"` followed by a hash of the rule
+   binding and the node name.
+ - `"subtask"` The running number, starting from `0`, of the action, as
+   given by the (deterministic) evaluation order of he defining
+   expression for the rule that defined the target.
+ - `"config"` The effective configuration for that target, a JSON
+   object.
+
+See also
+========
+
+**just(1)**