diff options
| -rw-r--r-- | doc/references.md | 570 |
1 files changed, 570 insertions, 0 deletions
diff --git a/doc/references.md b/doc/references.md new file mode 100644 index 0000000..88fd53a --- /dev/null +++ b/doc/references.md @@ -0,0 +1,570 @@ +# References + +This document contains a list of references and resources related to SVGU's +Starlark environment. + +The sources for the environment are located inside the +[pkg/config](../pkg/config) directory, especially the +[lib](../pkg/config/lib) package. + +## Starlark + +[Starlark](https://starlark.net) is a dialect of Python designed for use as a +configuration language. It is simple, safe, and expressive. +Originally called Skylark, Starlark is commonly used with +[Bazel](https://bazel.build)-like build systems, but it is not tied to any +particular tool or project. + +SVGU's Starlark environment is based on the +[Starlark Go](https://go.starlark.net) implementation open sourced by Google. + +## Table of Contents + +- [Prelude](#prelude) + + [index](#index) + + [module](#module) +- [Bazaar](#bazaar) + + [bzr.BAZAAR](#bzrbazaar) +- [Fossil](#fossil) + + [fossil.FOSSIL](#fossilfossil) +- [Git](#git) + + [git.GIT](#gitgit) + + [git.GITHUB_DEFAULT_INSTANCE](#gitgithubdefaultinstance) + + [git.GITHUB_DEFAULT_REF](#gitgithubdefaultref) + + [git.SOURCEHUT_DEFAULT_INSTANCE](#gitsourcehutdefaultinstance) + + [git.SOURCEHUT_DEFAULT_REF](#gitsourcehutdefaultref) + + [git.GITLAB_DEFAULT_INSTANCE](#gitgitlabdefaultinstance) + + [git.GITLAB_DEFAULT_REF](#gitgitlabdefaultref) + + [git.BITBUCKET_DEFAULT_INSTANCE](#gitbitbucketdefaultinstance) + + [git.BITBUCKET_DEFAULT_REF](#gitbitbucketdefaultref) + + [git.GITILES_DEFAULT_REF](#gitgitilesdefaultref) + + [git.github](#gitgithub) + + [git.sourcehut](#gitsourcehut) + + [git.gitlab](#gitgitlab) + + [git.bitbucket](#gitbitbucket) + + [git.gitiles](#gitgitiles) +- [Mercurial](#mercurial) + + [hg.MERCURIAL](#hgmercurial) +- [Subversion](#subversion) + + [svn.SUBVERSION](#svnsubversion) + +## Prelude + +The [prelude](../pkg/config/lib/prelude/prelude.go) module contains a set of +built-in functions. + +These functions are the only required symbols to use SVGU in the configuration +file. + +Additional functions are helpers that can be used to simplify the configuration +file. For instance, [git.github](#gitgithub) will automatically construct the +template URLs for `dir` and `file` based on the repository's home URL. + +### index + +Initialize the index of module. +Should be called before any [module](#module) operations. + +`index(domain)` + +#### Parameters + +| Name | Type | Description | +|----------|----------|-----------------------------------------------------------| +| `domain` | `string` | The domain name of the repository, e.g. `go.example.com`. | + +#### Example + +```starlark +index(domain = "go.example.com") + +# ... +``` + +### module + +Register a module in the index. +Note that you cannot register multiple modules with the same name. + +> A module name cannot be empty, `.`, `..`, `\`, `/`, `:`, `*`, `?`, `"`, `<`, +> `>`, `|`, or any ASCII control character (i.e. `\x00` through `\x1f`). +> This is required to avoid problems with file systems. +> +> The module name cannot also be simply `index`. This is a limitation of the +> tool since it generates a file named `index.html` in the root of the output +> directory. +> +> To see the full list of reserved names, see the +> [invalidName](https://git.sr.ht/~n1c00o/svgu/tree/master/item/pkg/config/lib/prelude/prelude.go#L11) +> variable. + +#### Parameters + +| Name | Type | Description | +|--------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `string` | The name of the module. | +| `vcs` | `string` | The name of the Version Control System (VCS) used by the module. It should be one of `"bzr"`, `"fossil"`, `"git"`, `"hg"`, or `"svn"`. | +| `repo` | `string` | The URL of the repository's home, e.g. `https://src.example.com/foo`. | +| `dir` | `string` | A template URL to a page listing the various files inside a directory, e.g. `https://src.example.com/foo/tree/master{/dir}`. See the [go-source][go-source-tag] meta tag's documentation for more information about substitution variables. | +| `file` | `string` | A template URL to a page listing the lines inside a Go file, e.g. `https://src.example.com/foo/tree/master{/dir}/{file}#L{line}`. See the [go-source][go-source-tag] meta tag's documentation for more information about substitution variables. | + +#### Example + +```starlark +index(domain = "go.example.com") + +# Will be available as `go.example.com/foo`. +module( + name = "foo", + vcs = "git", + repo = "https://src.example.com/foo", + dir = "https://src.example.com/foo/tree/master{/dir}", + file = "https://src.example.com/foo/tree/master{/dir}/{file}#L{line}", +) + +# Will be available as `go.example.com/bar/baz`. +module( + name = "bar/baz", + vcs = "svn", + repo = "https://src.example.com/bar/baz", + dir = "https://src.example.com/bar/baz{/dir}", + file = "https://src.example.com/bar/baz{/dir}/{file}#L{line}", +) +``` + +## Bazaar + +The [bzr](../pkg/config/lib/bzr/bzr.star) (Bazaar) module contains a set +of utilities to work with modules hosted on +[GNU Bazaar][bzr-link] repositories. + +The module can be imported inside your configuration file by adding the +following code at the beginning of the file: + +```starlark +load("@svgu/bzr", "bzr") +``` + +### bzr.BAZAAR + +`"bzr"` \ +A constant containing the name of the VCS as required by the +[`module`](#module) function. + +#### Example + +```starlark +module( + ... + vcs = bzr.BAZAAR, +) +``` + +## Fossil + +The [fossil](../pkg/config/lib/fossil/fossil.star) module contains a set +of utilities to work with modules hosted on +[Fossil][fossil-link] repositories. + +The module can be imported inside your configuration file by adding the +following code at the beginning of the file: + +```starlark +load("@svgu/fossil", "fossil") +``` + +### fossil.FOSSIL + +`"fossil"` \ +A constant containing the name of the VCS as required by the +[`module`](#module) function. + +#### Example + +```starlark +module( + ... + vcs = fossil.FOSSIL, +) +``` + +## Git + +The [git](../pkg/config/lib/git/git.star) module contains a set of utilities +to work with modules hosted on [Git][git-link] repositories. + +The module can be imported inside your configuration file by adding the +following code at the beginning of the file: + +```starlark +load("@svgu/git", "git") +``` + +### git.GIT + +`"git"` \ +A constant containing the name of the VCS as required by the +[`module`](#module) function. + +#### Example + +```starlark +module( + ... + vcs = git.GIT, +) +``` + +### git.GITHUB_DEFAULT_INSTANCE + +`"https://github.com"` \ +A constant containing the default GitHub instance to use when the repository +is hosted on [GitHub][github-link]. + +### git.GITHUB_DEFAULT_REF + +`"main"` \ +A constant containing the default Git reference to use when the repository is +hosted on [GitHub][github-link]. + +See [GitHub's decision to rename master to main](https://github.com/github/renaming). + +### git.SOURCEHUT_DEFAULT_INSTANCE + +`"https://git.sr.ht"` \ +A constant containing the default SourceHut instance to use when the repository +is hosted on [Source Hut's Git hosting][sourcehut-git-link]. + +### git.SOURCEHUT_DEFAULT_REF + +`"master"` \ +A constant containing the default Git reference to use when the repository is +hosted on [Source Hut's Git hosting][sourcehut-git-link]. + +### git.GITLAB_DEFAULT_INSTANCE + +`"https://gitlab.com"` \ +A constant containing the default GitLab instance to use when the repository +is hosted on [GitLab][gitlab-link]. + +### git.GITLAB_DEFAULT_REF + +`"main"` \ +A constant containing the default Git reference to use when the repository is +hosted on [GitLab][gitlab-link]. + +See [GitLab's renaming from master to main announcement](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/). + +### git.BITBUCKET_DEFAULT_INSTANCE + +`"https://bitbucket.org"` \ +A constant containing the default Bitbucket instance to use when the repository +is hosted on [Bitbucket][bitbucket-link]. + +### git.BITBUCKET_DEFAULT_REF + +`"master"` \ +A constant containing the default Git reference to use when the repository is +hosted on [Bitbucket][bitbucket-link]. + +### git.GITILES_DEFAULT_REF + +`"master"` \ +A constant containing the default Git reference to use when the repository is +hosted on [Gitiles][gitiles-link] ([Gerrit][gerrit-link] with a Gitiles +front-end). + +### git.github + +A macro that registers a module hosted on [GitHub][github-link]. + +#### Parameters + +| Name | Type | Description | +|------------|----------|----------------------------------------------------------------------------------------------------| +| `name` | `string` | The name of the module. | +| `user` | `string` | The GitHub user or organization name. | +| `repo` | `string` | The GitHub repository name. | +| `ref` | `string` | The Git reference to use. Default to [`git.GITHUB_DEFAULT_REF`](#gitgithubdefaultref). | +| `instance` | `string` | The GitHub instance to use. Default to [`git.GITHUB_DEFAULT_INSTANCE`](#gitgithubdefaultinstance). | + +#### Example + +```starlark +load("@svgu/git", "git") + +index(domain = "go.example.com") + +# By default, the function assumes that the repository is hosted on +# https://github.com and the reference is `main`. +git.github( + name = "foo", + user = "example", + repo = "foo", +) + +# You can override the default reference and instance. +git.github( + name = "bar", + user = "example", + repo = "bar", + ref = "trunk", + instance = "https://github.example.com", +) +``` + +### git.gitlab + +A macro that registers a module hosted on [GitLab][gitlab-link]. + +#### Parameters + +| Name | Type | Description | +|------------|----------|----------------------------------------------------------------------------------------------------| +| `name` | `string` | The name of the module. | +| `user` | `string` | The GitLab user or organization name. | +| `repo` | `string` | The GitLab repository name. | +| `ref` | `string` | The Git reference to use. Default to [`git.GITLAB_DEFAULT_REF`](#gitgitlabdefaultref). | +| `instance` | `string` | The GitLab instance to use. Default to [`git.GITLAB_DEFAULT_INSTANCE`](#gitgitlabdefaultinstance). | + +#### Example + +```starlark +load("@svgu/git", "git") + +index(domain = "go.example.com") + +# By default, the function assumes that the repository is hosted on +# https://gitlab.com and the reference is `main`. +git.gitlab( + name = "foo", + user = "example", + repo = "foo", +) + +# You can override the default reference and instance. +git.gitlab( + name = "bar", + user = "example", + repo = "bar", + ref = "master", + instance = "https://gitlab.example.com", +) +``` + +### git.sourcehut + +A macro that registers a module hosted on +[Source Hut's Git hosting][sourcehut-git-link]. + +> Note: Source Hut's Git hosting is still in beta. Organization support is +> not yet available. + +#### Parameters + +| Name | Type | Description | +|------------|----------|--------------------------------------------------------------------------------------------------------------| +| `name` | `string` | The name of the module. | +| `user` | `string` | The Source Hut user name. | +| `repo` | `string` | The Source Hut repository name. | +| `ref` | `string` | The Git reference to use. Default to [`git.SOURCEHUT_DEFAULT_REF`](#gitsourcehutdefaultref). | +| `instance` | `string` | The Source Hut instance to use. Default to [`git.SOURCEHUT_DEFAULT_INSTANCE`](#gitsourcehutdefaultinstance). | + +#### Example + +```starlark +load("@svgu/git", "git") + +index(domain = "go.example.com") + +# By default, the function assumes that the repository is hosted on +# https://git.sr.ht and the reference is `master`. + +git.sourcehut( + name = "foo", + user = "example", + repo = "foo", +) + +# You can override the default reference and instance. +git.sourcehut( + name = "bar", + user = "example", + repo = "bar", + ref = "main", + instance = "https://git.srht.example.com", +) +``` + +### git.bitbucket + +A macro that registers a module hosted on [Bitbucket][bitbucket-link]. + +It is likely that you want to override the default instance to include your +user in the URL. +To do so, you can use the `instance` parameter: + +```starlark +git.bitbucket( + ... + instance = "https://user@bitbucket.org/example", +) +``` + +As always, your mileage may vary. + +#### Parameters + +| Name | Type | Description | +|-------------|----------|-------------------------------------------------------------------------------------------------------------| +| `name` | `string` | The name of the module. | +| `workspace` | `string` | The Bitbucket workspace ID. | +| `repo` | `string` | The Bitbucket repository name. | +| `ref` | `string` | The Git reference to use. Default to [`git.BITBUCKET_DEFAULT_REF`](#gitbitbucketdefaultref). | +| `instance` | `string` | The Bitbucket instance to use. Default to [`git.BITBUCKET_DEFAULT_INSTANCE`](#gitbitbucketdefaultinstance). | + +#### Example + +```starlark +load("@svgu/git", "git") + +index(domain = "go.example.com") + +# By default, the function assumes that the repository is hosted on +# https://bitbucket.org and the reference is `master`. + +git.bitbucket( + name = "foo", + workspace = "example", + repo = "foo", +) + +# You can override the default reference and instance. +git.bitbucket( + name = "bar", + workspace = "example", + repo = "bar", + ref = "main", + instance = "https://bitbucket.example.com", +) +``` + +### git.gitiles + +A macro that registers a module hosted on [Gitiles][gitiles-link] +([Gerrit][gerrit-link] with Gitiles front-end). + +> Note: This is not a complete macro as I lack experience with Gerrit. +> Feel free to open a pull request if you want to improve it. + +#### Parameters + +| Name | Type | Description | +|------------|----------|-------------------------------------------------------------------------------------------| +| `name` | `string` | The name of the module. | +| `instance` | `string` | The Gitiles instance to use. | +| `repo` | `string` | The Gitiles repository path. | +| `ref` | `string` | The Git reference to use. Defaults to [`git.GITILES_DEFAULT_REF`](#gitgitilesdefaultref). | + +#### Example + +```starlark +load("@svgu/git", "git") + +index(domain = "go.example.com") + +# By default, the function assumes that the used reference is `master`. +git.gitiles( + name = "go", + instance = "https://go.googlesource.com", + repo = "go", +) + +# You can override the default reference. +git.gitiles( + name = "go", + instance = "https://go.googlesource.com", + repo = "go", + ref = "release-branch.go1.17", +) +``` + +## Mercurial + +The [hg](../pkg/config/lib/hg/hg.star) (Mercurial) module contains a set +of utilities to work with modules hosted on +[Mercurial][hg-link] repositories. + +The module can be imported inside your configuration file by adding the +following code at the beginning of the file: + +```starlark +load("@svgu/hg", "hg") +``` + +### hg.MERCURIAL + +`"hg"` \ +A constant containing the name of the VCS as required by the +[`module`](#module) function. + +#### Example + +```starlark +module( + ... + vcs = hg.MERCURIAL, +) +``` + +## Subversion + +The [svn](../pkg/config/lib/svn/svn.star) (Subversion) module contains +a set of utilities to work with modules hosted on +[Apache Subversion][svn-link] repositories. + +The module can be imported inside your configuration file by adding the +following code at the beginning of the file: + +```starlark +load("@svgu/svn", "svn") +``` + +### svn.SUBVERSION + +`"svn"` \ +A constant containing the name of the VCS as required by the +[`module`](#module) function. + +#### Example + +```starlark +module( + ... + vcs = svn.SUBVERSION, +) +``` + +[svn-link]: https://subversion.apache.org/ + +[hg-link]: https://www.mercurial-scm.org/ + +[git-link]: https://git-scm.com/ + +[fossil-link]: https://www.fossil-scm.org/ + +[bzr-link]: https://bazaar.canonical.com/ + +[bitbucket-link]: https://bitbucket.org + +[github-link]: https://github.com/about + +[sourcehut-git-link]: https://man.sr.ht/git.sr.ht/ + +[gitlab-link]: https://about.gitlab.com + +[gitiles-link]: https://gerrit.googlesource.com/gitiles/ + +[gerrit-link]: https://www.gerritcodereview.com/ + +[go-source-tag]: https://github.com/golang/gddo/wiki/Source-Code-Links |