NAME

       just-mr-repository-config - The format of the repository config used by just-mr(1)

DESCRIPTION

       In  order  for the just-mr(1) tool to generate a repository configuration file usable by the justbuild(1)
       multi-repository build system, it  requires  a  configuration  file  describing  repositories  and  their
       dependencies.

       The  file is read as JSON.  Any other serialization describing the same JSON object is equivalent.  It is
       assumed that in JSON objects keys occur at most once; it is implementation defined how repetitions of the
       same key are treated.

   Workspace root description
       A repository’s workspace root description provides information about the location of  source  files.   It
       can  be  an explicit description, given as a JSON object, or an implicit one, given as the global name of
       another repository, from which the workspace root can be inferred.

       Explicit workspace roots can be of several types, distinguishable by the value of the key "type"  in  the
       JSON object.  Depending on this value, other fields in the object are also supported.

   "file"
       It defines as workspace root a directory on the file system.

       The following fields are supported:

       • "path" provides the root directory containing the source files.  This entry is mandatory.

   "archive" / "zip"
       They  define as workspace root a remote archive.  The only difference between the two types is the nature
       of the archive: a tarball (preferably compressed) in the case of "archive", or a compressed zip  or  7zip
       file in the case of "zip".

       The following fields are supported:

       • "content"  provides  the  Git blob hash of the archive file.  This has to be specified in hex encoding.
         This entry is mandatory.

       • "fetch" specifies the URL to the remote archive.  This entry is mandatory.

       • "distfile" provides an alternative name for the archive file.  This entry is optional.  If missing, the
         basename of the fetch URL is used.

       • "mirrors" is an optional list of alternative locations to try to fetch  from  if  contacting  the  main
         fetch location fails.  This entry is optional.

       • "sha256",

       • "sha512"  provide optional checksum hashes in order to verify the integrity of the remote site archive.
         These have to be provided in hex encoding.  These checks are only performed  if  the  archive  file  is
         actually downloaded from the (potentially untrusted) network and not already available locally.

       • "subdir" specifies the subdirectory withing the unpacked archive.  This entry is optional.  If missing,
         the root directory of the archive is used.

   "foreign file"
       Define  a  root  as  consisting  of  single  file  with  given  content at a specific name with specified
       executable bit.

       The following fields are supported.

       • "content", "fetch", "distfile", "mirrors", "sha256", and "sha512" specify the file content in the  same
         way as they specify the archive content for an "archive" repository.

       • "name"  specifies the name the content should have in the defined root.  It has to be a plain file name
         without implicitly specified subdirs.  This field is mandatory.

       • "executable" is a boolean indicating whether the fetched file should be provided  with  the  executable
         bit.  Defaults to false.

   "git"
       It defines as workspace root a part of a Git repository.

       The following fields are supported:

       • "repository"  provides  the  URL  of the Git repository.  This entry is mandatory.  Note that only URLs
         starting with /, ./, or file:// are considered file URLs.

       • "commit" contains the commit hash.  This has to be specified in hex encoding.  This entry is mandatory.

       • "branch" provides the branch name, with the promise that it contains the aforementioned  commit.   This
         entry is mandatory.

       • "mirrors"  is  an  optional  list  of alternative locations to try to fetch from if contacting the main
         repository fails.  This entry is optional.

       • "subdir" specifies the subdirectory containing the distribution files.  This  entry  is  optional.   If
         missing, the root directory of the Git repository is used.

       • "inherit  env"  provides  a  list  of  variables.   When just-mr shells out to git, those variables are
         inherited from the environment just-mr is called within, if set there.

   "git tree"
       It defines as workspace root as a fixed git tree, given by the corresponding tree  identifier.   If  that
       tree  is  not known already to just-mr, a specified command will be executed in a fresh directory that is
       expected to produce the given tree somewhere below the working directory.

       This type of root is the way builds against sources versioned in arbitrary version-control systems can be
       carried out.  The command then would be a call to the version control system requesting an  export  at  a
       particular version.

       As  the  root  is already fully determined by the specified git tree identifier, the corresponding action
       need not be fully isolated.  In fact, to check  out  a  repository  it  might  be  necessary  to  provide
       credentials  (which  do  not  matter for the checked-out tree, but differ from user to user).  To support
       this, the description of the  root  can  specify  environment  variables  to  inherit  from  the  ambient
       environment.  E.g., SSH_AUTH_SOCK can be specified here to support ssh-based authentication.

       The following fields are supported:

       • "id" provides the Git tree identifier.  This entry is mandatory.

       • "cmd"  provides  a  list  of  strings  forming a command which promises that, when executed in an empty
         directory (anywhere in the file system), creates in that directory a directory structure containing the
         promised Git tree (either top-level or in some subdirectory).  This entry is mandatory.

       • "env" provides a map of envariables to be set for executing the command.

       • "inherit env" provides a list of variables to be inherited  from  the  environment  just-mr  is  called
         within, if set there.

   "distdir"
       It  defines  as  workspace root a directory with the distribution archives of the specified repositories.
       Usually this root is realized as a Git tree in the Git repository in justbuild’s local build root.

       The following fields are supported:

       • "repositories" provides a list of global names of repositories.  This entry is mandatory.

   "computed"
       It defines a computed root, typically to be used as root by other repositories.  A computed root is given
       as the artifacts map of an export target of a content-fixed repository.  Computed  roots  themselves  are
       content fixed; the dependency of computed roots on one another must be cycle free.

       The following fields are supported:

       • "repo" specifies the repository the export target belongs to.  This entry is mandatory.

       • "target"  specifies  the  export target within the given repository in module-name form.  This entry is
         mandatory.

       • "config" specifies the configuration at which to evaluate the export target.  This  entry  is  optional
         and defaults to the empty map.

   "tree structure"
       It evaluates to the given root but with all files and symlinks replaced by empty blobs.  A tree structure
       root  is given by a content-fixed workspace of a repository.  Tree structure roots themselves are content
       fixed; the dependency of tree structure roots on one another must be cycle free.

       The following fields are supported:

       • "repo" specifies the repository whose workspace root must be evaluated.  This entry is mandatory.

   Additional keys
       The key "pragma" is reserved for type-specific repository directives which alter the workspace root.   It
       is  given  as a JSON object.  The different workspace roots might support different keys for this object;
       unsupported keys are always ignored.

       For a "file" workspace root the pragma key "to_git" is supported.  If its value is true then it indicates
       that the workspace root should be returned as a Git tree.  If the root directory is already part of a Git
       repository, its Git tree identifier is used; otherwise, the workspace root will be realized as a Git tree
       in the Git repository in justbuild’s local build root.

       For all workspace roots except "distdir", "computed", and "tree structure", the pragma key  "special"  is
       supported.   If its value is "ignore" then it indicates that the workspace root should ignore all special
       (i.e., neither file, executable, nor tree) entries.  For a "file" workspace  root  or  for  an  "archive"
       workspace  root  a  value  of  "resolve-completely"  indicates that the workspace root should resolve all
       confined relative symbolic links, while a value of "resolve-partially" indicates that the workspace  root
       should  resolve  only the confined relative upwards symbolic links; for a "file" workspace root these two
       values imply "to_git" is true.

       For all workspace roots the pragma key "absent" is supported.  If its value is  true  then  it  indicates
       that  an  absent  root  should  be  generated,  i.e., one given only by its Git tree without any explicit
       witnessing repository.

   Repository description
       A repository description is defined as a JSON object, containing a workspace root description,  directory
       roots and names for targets, rules, and expressions files, and bindings to other repositories.

       Specifically, the following fields are supported:

       • "repository" contains a workspace root description.  This entry is mandatory.

       • "target_root",

       • "rule_root",

       • "expression_root"  define  the  root directories for the targets, rules, and expressions, respectively.
         If provided, they are passed on expanded to the workspace root of the repository named by their value.

       • "target_file_name",

       • "rule_file_name",

       • "expression_file_name" refer to the name of the files containing the targets, rules,  and  expressions,
         respectively,  located relative to the corresponding root directories.  These entries are optional.  If
         provided, they are passed on as-is.

       • "bindings" provides a JSON object defining dependencies on other repositories.  The object’s  keys  are
         strings  defining  local repository names, while the values are the corresponding global names of those
         repositories.  If provided, this entry is passed on as-is.

   Repository configuration format
       The repository configuration format is structured as a JSON object.  The following fields are supported:

       • "main" contains a JSON string that determines which of the provided repositories is considered the main
         repository.   This  entry  is  optional,  and  if  omitted,  it  will  be  omitted  in  the   generated
         just-repository-config.

       • "repositories"  contains  a  JSON  object,  where  each  key is the global name of a repository and its
         corresponding value is the repository description.

   Additional keys
       Any JSON object described in this format might have additional keys  besides  the  ones  mentioned.   The
       current  strategy of just-mr(1) is to accept and ignore them.  Users should be aware that future versions
       of this format might give specific meanings to these extra keys.

See also

       justbuild(1), just-mr(1), just-repository-config(5)

                                                            JUST-MR REPOSITORY CONFIG(5) | File Formats Manual()