From 49956ae4a353344a4f4f6659b46d27312752c236 Mon Sep 17 00:00:00 2001 From: Michael McLoughlin Date: Tue, 26 Oct 2021 22:23:37 -0700 Subject: [PATCH] meta: extra fields (#126) Expand the metadata properties with additional fields, intended for use in code generation (see #94). --- CITATION.bib | 2 +- README.md | 2 +- internal/tools/docgen/templates/cff.tmpl | 4 +-- internal/tools/docgen/templates/readme.tmpl | 22 ++++++------ internal/tools/docgen/templates/zenodo.tmpl | 4 +-- meta/cite.go | 6 ++-- meta/meta.go | 39 ++++++++++++++++++--- 7 files changed, 55 insertions(+), 24 deletions(-) diff --git a/CITATION.bib b/CITATION.bib index 27ad19a..19fec23 100644 --- a/CITATION.bib +++ b/CITATION.bib @@ -3,7 +3,7 @@ @misc{addchain author = {Michael B. McLoughlin}, year = 2021, month = may, - howpublished = {Github repository \url{https://github.com/mmcloughlin/addchain}}, + howpublished = {Repository \url{https://github.com/mmcloughlin/addchain}}, version = {0.3.0}, license = {BSD 3-Clause License}, doi = {10.5281/zenodo.4758226}, diff --git a/README.md b/README.md index 5ff6fc9..efc3866 100644 --- a/README.md +++ b/README.md @@ -363,7 +363,7 @@ release](https://github.com/mmcloughlin/addchain/releases/tag/v0.3.0). author = {Michael B. McLoughlin}, year = 2021, month = may, - howpublished = {Github repository \url{https://github.com/mmcloughlin/addchain}}, + howpublished = {Repository \url{https://github.com/mmcloughlin/addchain}}, version = {0.3.0}, license = {BSD 3-Clause License}, doi = {10.5281/zenodo.4758226}, diff --git a/internal/tools/docgen/templates/cff.tmpl b/internal/tools/docgen/templates/cff.tmpl index 8bc8845..4ed6225 100644 --- a/internal/tools/docgen/templates/cff.tmpl +++ b/internal/tools/docgen/templates/cff.tmpl @@ -1,6 +1,6 @@ cff-version: 1.2.0 message: "If you use addchain in your work, a citation would be appreciated using the following metadata." -title: "addchain: Cryptographic Addition Chain Generation in Go" +title: "{{ .Meta.Title }}" authors: - family-names: "McLoughlin" given-names: "Michael Ben" @@ -8,7 +8,7 @@ authors: version: "{{ .Meta.ReleaseVersion }}" date-released: "{{ .Meta.ReleaseDate }}" license: BSD-3-Clause -repository-code: https://github.com/mmcloughlin/addchain +repository-code: {{ .Meta.RepositoryURL }} doi: "{{ .Meta.DOI }}" identifiers: - type: doi diff --git a/internal/tools/docgen/templates/readme.tmpl b/internal/tools/docgen/templates/readme.tmpl index e50f0e4..f21002d 100644 --- a/internal/tools/docgen/templates/readme.tmpl +++ b/internal/tools/docgen/templates/readme.tmpl @@ -7,7 +7,7 @@ DOI: {{ .Meta.DOI }}

-

Cryptographic Addition Chain Generation in Go

+

{{ .Meta.Description }}

`addchain` generates short addition chains for exponents of cryptographic interest with [results](#results) rivaling the best hand-optimized chains. @@ -98,7 +98,7 @@ produce high quality results in an automated code generation tool. ### Command-line Interface Install a pre-compiled [release -binary](https://github.com/mmcloughlin/addchain/releases): +binary]({{ .Meta.RepositoryURL }}/releases): ``` curl -sSfL https://git.io/addchain | sh -s -- -b /usr/local/bin @@ -107,7 +107,7 @@ curl -sSfL https://git.io/addchain | sh -s -- -b /usr/local/bin Alternatively build from source: ``` -go install github.com/mmcloughlin/addchain/cmd/addchain@latest +go install {{ .Meta.Module }}/cmd/addchain@latest ``` Search for a curve25519 field inversion addition chain with: @@ -127,7 +127,7 @@ Output: Install: ``` -go get -u github.com/mmcloughlin/addchain +go get -u {{ .Meta.Module }} ``` Algorithms all conform to the {{ sym "alg" "ChainAlgorithm" }} or @@ -199,7 +199,7 @@ about their precise definition and poor results from early experiments. Furthermore, this library does not apply weights to the heuristics as suggested in the paper, rather it simply uses the first that applies. However both of these remain [possible avenues for -improvement](https://github.com/mmcloughlin/addchain/issues/26). +improvement]({{ .Meta.RepositoryURL }}/issues/26). #### References @@ -276,7 +276,7 @@ These micro-optimizations were vital in closing the gap between `addchain`'s automated approaches and hand-optimized chains. This technique is reminiscent of basic passes in optimizing compilers, raising the question of whether other [compiler optimizations could apply to addition -chains](https://github.com/mmcloughlin/addchain/issues/24)? +chains]({{ .Meta.RepositoryURL }}/issues/24)? > I have not seen this method discussed in the literature. Please help me find references to prior art if you know any. @@ -286,14 +286,14 @@ If you use `addchain` in your research a citation would be appreciated. Citing a specific release is preferred, since they are [archived on Zenodo]({{ .Meta.ConceptDOIURL }}) and assigned a DOI. Please use the following BibTeX to cite the most recent [{{ .Meta.ReleaseVersion }} -release]({{ .Meta.GithubReleaseURL }}). +release]({{ .Meta.ReleaseURL }}). ```bib {{ .Meta.Citation -}} ``` If you need to cite a currently unreleased version please consider [filing an -issue](https://github.com/mmcloughlin/addchain/issues/new) to request a new +issue]({{ .Meta.RepositoryURL }}/issues/new) to request a new release, or to discuss an appropriate format for the citation. ## Thanks @@ -308,11 +308,11 @@ Glancy](https://twitter.com/mglancy) for review. Contributions to `addchain` are welcome: -* [Submit bug reports](https://github.com/mmcloughlin/addchain/issues/new) to +* [Submit bug reports]({{ .Meta.RepositoryURL }}/issues/new) to the issues page. -* Suggest [test cases](https://github.com/mmcloughlin/addchain/blob/e6c070065205efcaa02627ab1b23e8ce6aeea1db/internal/results/results.go#L62) +* Suggest [test cases]({{ .Meta.RepositoryURL }}/blob/e6c070065205efcaa02627ab1b23e8ce6aeea1db/internal/results/results.go#L62) or update best-known hand-optimized results. -* Pull requests accepted. Please discuss in the [issues section](https://github.com/mmcloughlin/addchain/issues) +* Pull requests accepted. Please discuss in the [issues section]({{ .Meta.RepositoryURL }}/issues) before starting significant work. ## License diff --git a/internal/tools/docgen/templates/zenodo.tmpl b/internal/tools/docgen/templates/zenodo.tmpl index 1b01e9c..d806d2d 100644 --- a/internal/tools/docgen/templates/zenodo.tmpl +++ b/internal/tools/docgen/templates/zenodo.tmpl @@ -1,6 +1,6 @@ { - "title": "mmcloughlin/addchain: {{ .Meta.ReleaseTag }}", - "description": "Cryptographic Addition Chain Generation in Go", + "title": "{{ .Meta.FullName }}: {{ .Meta.ReleaseTag }}", + "description": "{{ .Meta.Description }}", "version": "{{ .Meta.ReleaseVersion }}", "publication_date": "{{ .Meta.ReleaseDate }}", "upload_type": "software", diff --git a/meta/cite.go b/meta/cite.go index 69f8b1b..bfaae04 100644 --- a/meta/cite.go +++ b/meta/cite.go @@ -35,12 +35,12 @@ func (p *Properties) WriteCitation(w io.Writer) error { field := func(key, value string) { tw.Linef(" %s\t=\t%s,", key, value) } str := func(key, value string) { field(key, "{"+value+"}") } - tw.Linef("@misc{addchain,") - str("title", "addchain: Cryptographic Addition Chain Generation in Go") + tw.Linef("@misc{%s,", p.Name) + str("title", p.Title()) str("author", "Michael B. McLoughlin") field("year", strconv.Itoa(date.Year())) field("month", strings.ToLower(date.Month().String()[:3])) - str("howpublished", "Github repository \\url{https://github.com/mmcloughlin/addchain}") + str("howpublished", "Repository \\url{"+p.RepositoryURL()+"}") str("version", p.ReleaseVersion) str("license", "BSD 3-Clause License") str("doi", p.DOI) diff --git a/meta/meta.go b/meta/meta.go index 89aa383..da8b0e2 100644 --- a/meta/meta.go +++ b/meta/meta.go @@ -1,7 +1,11 @@ // Package meta defines properties about this project. package meta -import "time" +import ( + "fmt" + "path" + "time" +) // VersionTagPrefix is the prefix used on Git tags corresponding to semantic // version releases. @@ -9,6 +13,15 @@ const VersionTagPrefix = "v" // Properties about this software package. type Properties struct { + // Name is the project name. + Name string + + // FullName is the "owner/name" identifier for the project. + FullName string + + // Description is the concise project headline. + Description string + // BuildVersion is the version that was built. Typically populated at build // time and will typically be empty for non-release builds. BuildVersion string @@ -31,6 +44,9 @@ type Properties struct { // Meta defines specific properties for the current version of this software. var Meta = &Properties{ + Name: "addchain", + FullName: "mmcloughlin/addchain", + Description: "Cryptographic Addition Chain Generation in Go", BuildVersion: buildversion, ReleaseVersion: releaseversion, ReleaseDate: releasedate, @@ -39,6 +55,11 @@ var Meta = &Properties{ ZenodoID: zenodoid, } +// Title is a full project title, suitable for a citation. +func (p *Properties) Title() string { + return fmt.Sprintf("%s: %s", p.Name, p.Description) +} + // IsRelease reports whether the built version is a release. func (p *Properties) IsRelease() bool { return p.BuildVersion == p.ReleaseVersion @@ -49,9 +70,19 @@ func (p *Properties) ReleaseTag() string { return VersionTagPrefix + p.ReleaseVersion } -// GithubReleaseURL returns the URL to the release page on Github. -func (p *Properties) GithubReleaseURL() string { - return "https://github.com/mmcloughlin/addchain/releases/tag/" + p.ReleaseTag() +// Module returns the Go module path. +func (p *Properties) Module() string { + return path.Join("github.com", p.FullName) +} + +// RepositoryURL returns a URL to the hosted repository. +func (p *Properties) RepositoryURL() string { + return "https://" + p.Module() +} + +// ReleaseURL returns the URL to the release page. +func (p *Properties) ReleaseURL() string { + return fmt.Sprintf("%s/releases/tag/%s", p.RepositoryURL(), p.ReleaseTag()) } // ReleaseTime returns the release date as a time object.