3 Ebuild - Exported Functions

8.12

3 Ebuild - Exported Functions🔗ℹ

Functions used to be prefixed with "ebuild:" and "metadata:". If you still wish to keep this naming scheme, use:

(require (prefix-in ebuild: ebuild/ebuild)
(prefix-in metadata: ebuild/metadata))

3.1 Ebuild Functions🔗ℹ

3.1.1 Constraint Flag🔗ℹ

struct
(struct cflag (predicate content)
    #:extra-constructor-name make-cflag)
  predicate : (or/c #f string?)
  content : (listof (or/c cflag? string?))

No restrictive contracts are enforced upon neither predicate nor content for now.

cflags can be nested, for recursively transforming them, see cflag->string.

predicate symbolizes the logical ebuild condition to satisfy.

Examples:

> (define restrict
    (cflag "||" (list "qt5" "gtk")))
> restrict
(cflag "||" '("qt5" "gtk"))
> (cflag->string restrict)
"|| ( qt5\n\tgtk )"
> (display (cflag->string restrict))
|| ( qt5
gtk )
> (define iuse
    (cflag "X?" (list (cflag "gtk?" (list "x11-libs/gtk+:3"))
                      (cflag "qt5?" (list "dev-qt/qtcore:5")))))
> iuse
(cflag
"X?"
(list
  (cflag "gtk?" '("x11-libs/gtk+:3"))
  (cflag "qt5?" '("dev-qt/qtcore:5"))))
> (for ([i '(0 1 2)])
    {define s (cflag->string iuse i)}
    (printf "~v~%" s)
    (displayln s))
"X? ( gtk? ( x11-libs/gtk+:3 )\nqt5? ( dev-qt/qtcore:5 ) )"
X? ( gtk? ( x11-libs/gtk+:3 )
qt5? ( dev-qt/qtcore:5 ) )
"X? ( gtk? ( x11-libs/gtk+:3 )\n\tqt5? ( dev-qt/qtcore:5 ) )"
X? ( gtk? ( x11-libs/gtk+:3 )
qt5? ( dev-qt/qtcore:5 ) )
"X? ( gtk? ( x11-libs/gtk+:3 )\n\t\tqt5? ( dev-qt/qtcore:5 ) )"
X? ( gtk? ( x11-libs/gtk+:3 )
qt5? ( dev-qt/qtcore:5 ) )

procedure
(cflag->string fl [tabs #:flat? flat?]) → string?
  fl : cflag?
  tabs : exact-nonnegative-integer? = 1
  flat? : boolean? = #f

Extracts cflag contents to a string.

cflag->string calls itself recursively if a cflag is encountered inside currently given fl variable.

Each internal recursive call increments tabs by 1. If tabs is given (grater than 0), then that tab step is applied to the result.

If flat? is true, then the produced string does not contain neither tabs nor newlines.

Example:

> (cflag->string (cflag "||" (list "qt5" "gtk")) #:flat? #t)
"|| ( qt5 gtk )"

3.1.2 Source URL🔗ℹ

Functions and structs used to create SRC_URI ebuild variable.

struct
(struct src-uri (flag url name)
    #:extra-constructor-name make-src-uri)
  flag : (or/c #f string?)
  url : string?
  name : (or/c #f string?)

Struct to hold URLs of SRC_URI.

Fields represent inside a ebuild:

flag — condition to grab given URL
url — any URL, maybe with shell variables inside
name — optional file name to which source downloaded from url will be renamd to, ie.: "${P}.tag.gz"

procedure
(src-uri-src su) → string?
su : src-uri

Creates a source string from given src-uri.

Example:

> (src-uri-src
(src-uri
"doc" "https://mywebsite.com/${PN}-docs-${PV}.zip" "${P}-docs.zip"))
"https://mywebsite.com/${PN}-docs-${PV}.zip -> ${P}-docs.zip"

procedure
(src-uri->string su) → string?
su : src-uri

Creates a source string, with optional flag, from given src-uri.

Example:

> (src-uri->string
(src-uri
"doc" "https://mywebsite.com/${PN}-docs-${PV}.zip" "${P}-docs.zip"))
"doc ( https://mywebsite.com/${PN}-docs-${PV}.zip -> ${P}-docs.zip )"

3.1.3 Shell Variables🔗ℹ

procedure
(list-as-variable name lst) → (or/c #f string?)
name : string?
lst : (or/c #f (listof (or/c number? string? symbol?)))

Returns a string that can be used in creating POSIX-like shell scripts. "name=\"value\"" if only value in list lst is a string or 2 or more of any type of values or "name=value" if given list lst with one value that is a number or symbol. If #f is given as lst, then #f is returned.

Examples:

> (list-as-variable "TURN_ON_FEATURE" '(YES))
"TURN_ON_FEATURE=YES"
> (list-as-variable "TURN_ON_FEATURES" '(THIS THAT))
"TURN_ON_FEATURES=\"THIS THAT\""

procedure
(as-variable name value ...) → (or/c #f string?)
name : string?
value : (or/c #f (or/c number? string? symbol?))

Wrapper for list-as-variable.

Example:

> (as-variable "TURN_ON_FEATURE" 'YES)
"TURN_ON_FEATURE=YES"

syntax
(make-variable name)

name : (or/c identifier? string? symbol?)

Uses as-variable. If name is an identifier, then it is the name of variable and the value is what that name resolves to. If name is a string or a symbol then it is passed to both name and value of as-variable (symbol is converted to a string).

Examples:

> (make-variable "this_variable_will_probably_change")
"this_variable_will_probably_change=\"this_variable_will_probably_change\""
> (define Z "Zzz...")
> (make-variable Z)
"Z=\"Zzz...\""

procedure
(list-as-array-variable name lst) → (or/c #f string?)
name : string?
lst : (or/c #f (listof (or/c number? string? symbol?)))

Simialr to list-as-variable, except for arrays.

Example:

> (list-as-array-variable "FEATURES" '("mirror" "test"))
"FEATURES=(\"mirror\" \"test\")"

procedure
(as-array-variable name value ...) → (or/c #f string?)
name : string?
value : (or/c #f (or/c number? string? symbol?))

Wrapper for list-as-variable.

Example:

> (as-array-variable "FEATURES" "mirror" "test")
"FEATURES=(\"mirror\" \"test\")"

syntax
(make-array-variable name)

name : (or/c identifier? string? symbol?)

Uses list-as-array-variable and as-array-variable.

Examples:

> (make-array-variable "this_variable_will_probably_change")
"this_variable_will_probably_change=(\"this_variable_will_probably_change\")"
> (define FEATURES '("mirror" "test"))
> (make-array-variable FEATURES)
"FEATURES=(\"mirror\" \"test\")"

3.1.4 Object manipulation🔗ℹ

syntax
(ebuild-append! id obj lst)

   id : identifier?
   obj : (is-a? ebuild%)
   lst : list?

Calls append! method of a given obj ebuild% object.

syntax
(ebuild-concat! id obj v)

   id : identifier?
   obj : (is-a? ebuild%)
   v : any/c

Calls concat! method of a given obj ebuild% object.

3.2 Shell Script Functions🔗ℹ

(require ebuild/sh-function)

package: ebuild-lib

3.2.1 POSIX shell script function creation🔗ℹ

Ease the creation of ebuild scripts’ "body".

struct
(struct sh-function (name body)
    #:extra-constructor-name make-sh-function)
  name : string?
  body : string?

Example:

> (sh-function "my_function" "do_something || die")
#<sh-function>

procedure
(sh-function->string sf) → string?
sf : sh-function?

Creates a string that looks like a function from as POSIX shell script.

Example:

> (display (sh-function->string
(sh-function "my_function" "do_something || die")))
my_function() {
do_something || die
}

procedure
(unroll-sh-functions lst) → string?
lst : (listof sh-function?)

Uses sh-function->string to create a shell script body string. Basically it is some POSIX shell script functions.

procedure
(make-script #:indent indent strs ...) → string?
indent : exact-integer?
strs : string?

Produces a shell script body from any amount of given strings, with the indentation indent represented by tab characters (this its to comply with the ebuild format where we indent with tabs).

This function exists to ease writing custom ebuild (shell script) functions.

Example:

> (display (sh-function->string
(sh-function "my_function" (make-script "do_something || die"))))
my_function() {
do_something || die
}

3.3 Metadata Functions🔗ℹ

The structname->xexpr procedures are primarily used internally but are also exported because sometimes they can be handy.

3.3.1 XML tags🔗ℹ

parameter
(metadata-empty-tags) → list?
(metadata-empty-tags list) → void?
list : list?
= (list 'stabilize-allarches)

Parameter that determines shorthanded tags list passed to empty-tag-shorthand.

3.3.2 localized🔗ℹ

struct
(struct localized (lang data)
    #:extra-constructor-name make-localized)
  lang : (or/c #f string? symbol?)
  data : string?

"Intermediate" strcture inherited by in longdescription and doc.

procedure
(localized->xexpr lo element-name) → xexpr?
lo : localized?
element-name : symbol?

Converts lo localized struct to a x-expression, where the x-expression tag is element-name.

3.3.3 longdescription🔗ℹ

struct
(struct longdescription localized ()
#:extra-constructor-name make-longdescription)

procedure
(longdescription->xexpr ld) → xexpr?
ld : longdescription?

Converts ld longdescription struct to a x-expression.

Examples:

> (define my-longdescription
    (longdescription
     "en"
     "This is some package providing some very important function,\n  everybody probably needs it, of course it is written in the best\n  programming language starting with letter R ;D"))
> (display-xml/content (xexpr->xml (longdescription->xexpr my-longdescription)))
<longdescription lang="en">

    This is some package providing some very important function, everybody
    probably needs it, of course it is written in the best programming language
    starting with letter R ;D

</longdescription>

3.3.4 maintainer🔗ℹ

struct
(struct maintainer (type proxied email name description)
    #:extra-constructor-name make-maintainer)
  type : (or/c 'person 'project 'unknown)
  proxied : (or/c #f 'yes 'no 'proxy)
  email : string?
  name : (or/c #f string?)
  description : (or/c #f string?)

procedure
(maintainer->xexpr maint) → xexpr?
maint : maintainer?

Converts maint maintainer struct to a x-expression.

Examples:

> (define my-maintainer
    (maintainer 'person #f "asd@asd.asd" "A.S.D." #f))
> (display-xml/content (xexpr->xml (maintainer->xexpr my-maintainer)))
<maintainer type="person">
  <email>
    asd@asd.asd
  </email>
  <name>
    A.S.D.
  </name>
</maintainer>

3.3.5 slots🔗ℹ

struct
(struct slot (name data)
    #:extra-constructor-name make-slot)
  name : string?
  data : string?

struct
(struct slots (lang slotlist subslots)
    #:extra-constructor-name make-slots)
  lang : (or/c #f string? symbol?)
  slotlist : (or/c #f (listof slot?))
  subslots : (or/c #f string?)

procedure
(slots->xexpr ss) → xexpr?
ss : slots?

Converts ss slots struct to a x-expression.

Examples:

> (define my-slots
    (slots #f (list (slot "1.9" "Provides libmypkg19.so.0")) #f))
> (display-xml/content (xexpr->xml (slots->xexpr my-slots)))
<slots>
  <slot name="1.9">
    Provides libmypkg19.so.0
  </slot>
</slots>

3.3.6 upstream🔗ℹ

struct
(struct upstreammaintainer (status email name)
    #:extra-constructor-name make-upstreammaintainer)
  status : (or/c #f 'active 'inactive 'unknown)
  email : (or/c #f string?)
  name : string?

struct
(struct remote-id (type tracker)
    #:extra-constructor-name make-remote-id)
   type :
(or/c 'bitbucket
      'codeberg 'cpan 'cpan-module 'cpe 'cran 'ctan
      'gentoo 'github 'gitlab 'google-code
      'heptapod
      'launchpad
      'osdn
      'pear 'pecl 'pypi
      'rubygems
      'sourceforge
      'vim)
  tracker : string?

struct
(struct doc localized ()
#:extra-constructor-name make-doc)

procedure
(docs->xexpr v) → xexpr?
v : (or/c #f string? (listof doc?))

Given a string or list of doc produces produces list of x-expressions. Given false produces a empty list.

struct
(struct upstream (maintainers changelog doc bugs-to remote-ids)
    #:extra-constructor-name make-upstream)
  maintainers : (listof upstreammaintainer?)
  changelog : (or/c #f string?)
  doc : (or/c #f string? (listof doc?))
  bugs-to : (or/c #f string?)
  remote-ids : (listof remote-id?)

procedure
(upstream->xexpr up) → xexpr?
up : upstream?

Converts up upstream struct to a x-expression.

Examples:

> (define my-upstream
    (upstream (list) #f #f #f (list (remote-id 'gitlab "asd/asd"))))
> (display-xml/content (xexpr->xml (upstream->xexpr my-upstream)))
<upstream>
  <remote-id type="gitlab">
    asd/asd
  </remote-id>
</upstream>
> (set-upstream-doc! my-upstream "https://asd.asd/docs.html")
> (display-xml/content (xexpr->xml (upstream->xexpr my-upstream)))
<upstream>
  <doc>
    https://asd.asd/docs.html
  </doc>
  <remote-id type="gitlab">
    asd/asd
  </remote-id>
</upstream>
> (set-upstream-doc! my-upstream (list (doc "en" "https://asd.asd/doc.html")
                                       (doc "pl" "https://asd.asd/dok.html")))
> (display-xml/content (xexpr->xml (upstream->xexpr my-upstream)))
<upstream>
  <doc lang="en">
    https://asd.asd/doc.html
  </doc>
  <doc lang="pl">
    https://asd.asd/dok.html
  </doc>
  <remote-id type="gitlab">
    asd/asd
  </remote-id>
</upstream>

3.3.7 use🔗ℹ

struct
(struct uflag (name data)
    #:extra-constructor-name make-uflag)
  name : string?
  data : (or/c #f string?)

struct
(struct use (lang flags)
    #:extra-constructor-name make-use)
  lang : (or/c #f string? symbol?)
  flags : (listof uflag?)

procedure
(use->xexpr us) → xexpr?
us : use?

Converts us use struct to a x-expression.

Examples:

> (define my-use
    (use #f (list (uflag "racket" "Build using dev-scheme/racket"))))
> (display-xml/content (xexpr->xml (use->xexpr my-use)))
<use>
  <flag name="racket">
    Build using dev-scheme/racket
  </flag>
</use>

3.4 Package Functions🔗ℹ

3.4.1 Package Version🔗ℹ

procedure
(release? v) → boolean?
v : any/c

Checks if given argement passes package-version validation. True if is a string a and has only digits and dots (".") and no more than one letter at the end.

Examples:

> (release? "")
#f
> (release? "0")
#t
> (release? "1q")
#t
> (release? "1.2.3a")
#t
> (release? "1.2.3abc")
#f

struct
(struct package-version (release phase pre rc patch revision)
    #:extra-constructor-name make-package-version)
  release : release?
  phase : (or/c #f 'a 'alpha 'b 'beta)
  pre : (or/c boolean? exact-nonnegative-integer?)
  rc : (or/c boolean? exact-nonnegative-integer?)
  patch : (or/c #f exact-positive-integer?)
  revision : (or/c #f exact-positive-integer?)

Example:

> (package-version "0a" 'beta 1 2 3 4)
(package-version "0a" 'beta 1 2 3 4)

procedure
(live-version [nines]) → package-version
nines : (and/c positive? exact-integer?) = 4

Generates a live package-version, that is: the one that has only 9s in "release" (all other fields are false). Optional number determines athe number of 9s.

Example:

> (live-version 8)
(package-version "99999999" #f #f #f #f #f)

procedure
(simple-version rel) → package-version
rel : release?

Generates a package-version with only a given rel (other fields are #f).

Example:

> (simple-version "8.0")
(package-version "8.0" #f #f #f #f #f)

procedure
(package-version->string ver) → string?
ver : package-version?

Converts package-version struct to a string.

Examples:

> (package-version->string (package-version "0a" 'beta 1 2 3 4))
"0a_beta_pre1_rc2_p3-r4"
> (package-version->string (live-version))
"9999"
> (package-version->string (simple-version "0a"))
"0a"

3.5 Repository Functions🔗ℹ

3.5.1 Layout🔗ℹ

struct
(struct layout ( masters
cache-formats
sign-commits
update-changelog
eapis-banned
eapis-deprecated
manifest-hashes
manifest-required-hashes
sign-manifests
thin-manifests)
    #:extra-constructor-name make-layout)
  masters : string?
  cache-formats : (listof string?)
  sign-commits : boolean?
  update-changelog : boolean?
  eapis-banned : (listof exact-integer?)
  eapis-deprecated : (listof exact-integer?)
  manifest-hashes : (listof string?)
  manifest-required-hashes : (listof string?)
  sign-manifests : boolean?
  thin-manifests : boolean?

parameter
(default-layout) → layout?
(default-layout layout) → void?
layout : layout?
=
(layout
"gentoo"
'("md5-dict")
#t
#f
'(0 1 2 3 4 5 6)
'()
'("BLAKE2B" "SHA512")
'("BLAKE2B")
#f
#t)

Parameter that determines default layout used when creating a repository% object.

procedure
(layout->string lo) → string?
lo : layout?

Converts lo layout struct to a string.

Example:

> (display (layout->string (default-layout)))
masters = gentoo
cache-formats = md5-dict
sign-commits = true
update-changelog = false
eapis-banned = 0 1 2 3 4 5 6
eapis-deprecated =
manifest-hashes = BLAKE2B SHA512
manifest-required-hashes = BLAKE2B
sign-manifests = false
thin-manifests = true

3.6 Manifest Functions🔗ℹ

(require ebuild/manifest)

package: ebuild-lib

This library does not use classes but rather structs. It is implemented in Typed Racket.

This library allows reading and creating Manifests.

Manifest files hold digests and size data for every file used by the package. More info about Manifests can be found in the Gentoo Developer manual.

3.6.1 Checksum🔗ℹ

struct
(struct checksum (type hash)
    #:extra-constructor-name make-checksum)
  type : string?
  hash : string?

Example:

> (checksum "BLAKE2B" "aa81a1a")
(checksum "BLAKE2B" "aa81a1a")

procedure
(list->checksums lst) → (listof checksum?)
lst : (listof string?)

Example:

> (list->checksums '("BLAKE2B" "aa81a1a" "SHA521" "b6095d4"))
(list (checksum "BLAKE2B" "aa81a1a") (checksum "SHA521" "b6095d4"))

procedure
(checksum->string cs) → string?
cs : checksum?

Example:

> (checksum->string (checksum "BLAKE2B" "aa81a1a"))
"BLAKE2B aa81a1a"

3.6.2 Dist🔗ℹ

struct
(struct dist (type file size checksums)
    #:extra-constructor-name make-dist)
  type : (or/c 'dist 'ebuild 'misc)
  file : string?
  size : integer?
  checksums : (listof checksum?)

Example:

> (dist 'dist "package-source.tar.gz" 100 (list (checksum "BLAKE2B" "aa81a1a")))
(dist 'dist "package-source.tar.gz" 100 (list (checksum "BLAKE2B" "aa81a1a")))

procedure
(string->dist-type str) → (or/c 'dist 'ebuild 'misc)
str : string?

Example:

> (string->dist-type "EBUILD")
'ebuild

procedure
(dist-type->string dist-type) → string?
dist-type : (or/c 'dist 'ebuild 'misc)

Example:

> (dist-type->string 'misc)
"MISC"

procedure
(string->dist str) → dist?
str : string?

Example:

> (string->dist "DIST gcc-9.4.0.tar.xz 72411232 BLAKE2B 4bb000d SHA512 dfd3500")
(dist
'dist
"gcc-9.4.0.tar.xz"
72411232
(list (checksum "BLAKE2B" "4bb000d") (checksum "SHA512" "dfd3500")))

procedure
(dist->string dst) → string?
dst : dist?

3.6.3 Manifest🔗ℹ

struct
(struct manifest (dists)
#:extra-constructor-name make-manifest)
dists : (listof dist?)

procedure
(read-manifest path) → manifest?
path : path-string?

procedure
(write-manifest mnfst [out]) → void?
mnfst : manifest?
out : output-port? = (current-output-port)

procedure
(save-manifest mnfst path) → void?
mnfst : manifest?
path : path-string?

1	About
2	Ebuild - Classes
3	Ebuild - Exported Functions
4	Ebuild Transformers
5	Ebuild Templates
6	Ebuild Tools
7	External Resources
	Index

3.1	Ebuild Functions
3.2	Shell Script Functions
3.3	Metadata Functions
3.4	Package Functions
3.5	Repository Functions
3.6	Manifest Functions