# Build API.

## Files

file | rpmcli.h
file | rpmbuild.h
| This is the *only* module users of librpmbuild should need to include.

file | rpmfc.h
| Structures and methods for build-time file classification.

file | rpmspec.h
| The rpmSpec and Package data structures used during build.

## Data Structures

struct | TriggerFileEntry
struct | Source
struct | ReadLevelEntry
struct | OpenFileInfo
struct | spectag_s
struct | spectags_s
struct | speclines_s
struct | rpmSpec_s
| The structure used to store values parsed from a spec file. More...
struct | Package_s
| The structure used to store values for a package. More...

## Defines

#define | PART_BASE 0
| rpmSpec file parser states.

## Typedefs

typedef enum rpmBuildFlags_e | rpmBuildFlags
| Bit(s) to control buildSpec() operation.
typedef struct Package_s * | Package
typedef struct ReadLevelEntry | RLE_t
typedef struct OpenFileInfo | OFI_t
typedef struct spectag_s * | spectag
typedef struct spectags_s * | spectags
typedef struct speclines_s * | speclines

## Enumerations

enum

rpmBuildFlags_e {
RPMBUILD_NONE = 0, RPMBUILD_PREP = (1 << 0), RPMBUILD_BUILD = (1 << 1), RPMBUILD_INSTALL = (1 << 2),
RPMBUILD_CHECK = (1 << 3), RPMBUILD_CLEAN = (1 << 4), RPMBUILD_FILECHECK = (1 << 5), RPMBUILD_PACKAGESOURCE = (1 << 6),
RPMBUILD_PACKAGEBINARY = (1 << 7), RPMBUILD_RMSOURCE = (1 << 8), RPMBUILD_RMBUILD = (1 << 9), RPMBUILD_STRINGBUF = (1 << 10),
RPMBUILD_RMSPEC = (1 << 11)
}

| Bit(s) to control buildSpec() operation. More...

## Functions

void | freeNames (void)
| Destroy uid/gid caches.
const char * | getUname (uid_t uid)
| Return cached user name from user id.
const char * | getUnameS (const char *uname)
| Return cached user name.
uid_t | getUidS (const char *uname)
| Return cached user id.
const char * | getGname (gid_t gid)
| Return cached group name from group id.
const char * | getGnameS (const char *gname)
| Return cached group name.
gid_t | getGidS (const char *gname)
| Return cached group id.
const char * | buildHost (void)
| Return build hostname.
rpm_time_t * | getBuildTime (void)
| Return build time stamp.
int | readLine (rpmSpec spec, int strip)
| Read next line from spec file.
void | closeSpec (rpmSpec spec)
| Stop reading from spec file, freeing resources.
void | handleComments (char *s)
| Truncate comment lines.
rpmParseState | isPart (const char *line)
| Check line for section separator, return next parser state.
uint32_t | parseUnsignedNum (const char *line, uint32_t *res)
| Parse an unsigned number.
void | addChangelogEntry (Header h, time_t time, const char *name, const char *text)
| Add changelog entry to header.
int | parseBuildInstallClean (rpmSpec spec, rpmParseState parsePart)
| Parse %build/%install/%clean section(s) of a spec file.
int | parseChangelog (rpmSpec spec)
| Parse %changelog section of a spec file.
int | parseDescription (rpmSpec spec)
| Parse %description section of a spec file.
int | parseFiles (rpmSpec spec)
| Parse %files section of a spec file.
int | parsePreamble (rpmSpec spec, int initialPackage)
| Parse tags from preamble of a spec file.
int | parsePrep (rpmSpec spec)
| Parse %prep section of a spec file.
rpmRC | parseRCPOT (rpmSpec spec, Package pkg, const char *field, rpmTag tagN, int index, rpmsenseFlags tagflags)
| Parse dependency relations from spec file and/or autogenerated output buffer.
int | parseScript (rpmSpec spec, int parsePart)
| Parse %pre et al scriptlets from a spec file.
int | parseExpressionBoolean (rpmSpec spec, const char *expr)
| Evaluate boolean expression.
char * | parseExpressionString (rpmSpec spec, const char *expr)
| Evaluate string expression.
rpmRC | doScript (rpmSpec spec, rpmBuildFlags what, const char *name, StringBuf sb, int test)
| Run a build script, assembled from spec file scriptlet section.
rpmRC | lookupPackage (rpmSpec spec, const char *name, int flag, Package *pkg)
| Find sub-package control structure by name.
Package | newPackage (rpmSpec spec)
| Create and initialize package control structure.
Package | freePackages (Package packages)
| Destroy all packages associated with spec file.
Package | freePackage (Package pkg)
| Destroy package control structure.
int | addReqProv (rpmSpec spec, Header h, rpmTag tagN, const char *N, const char *EVR, rpmsenseFlags Flags, uint32_t index)
| Add dependency to header, filtering duplicates.
int | rpmlibNeedsFeature (Header h, const char *feature, const char *featureEVR)
| Add rpmlib feature dependency.
int | processBinaryFiles (rpmSpec spec, int installSpecialDoc, int test)
| Post-build processing for binary package(s).
void | initSourceHeader (rpmSpec spec)
| Create and initialize header for source package.
int | processSourceFiles (rpmSpec spec)
| Post-build processing for source package.
int | parseSpec (rpmts ts, const char *specFile, const char *rootDir, const char *buildRoot, int recursing, const char *passPhrase, const char *cookie, int anyarch, int force)
| Parse spec file into spec control structure.
rpmRC | buildSpec (rpmts ts, rpmSpec spec, int what, int test)
| Build stages state machine driver.
rpmRC | packageBinaries (rpmSpec spec)
| Generate binary package(s).
rpmRC | packageSources (rpmSpec spec)
| Generate source package.
rpmSpec | newSpec (void)
| Create and initialize rpmSpec structure.
rpmSpec | freeSpec (rpmSpec spec)
| Destroy Spec structure.
int | rpmspecQuery (rpmts ts, QVA_t qva, const char *arg)
| Function to query spec file(s).
struct OpenFileInfo * | newOpenFileInfo (void)
spectag | stashSt (rpmSpec spec, Header h, rpmTag tag, const char *lang)
| stashSt.
int | addSource (rpmSpec spec, Package pkg, const char *field, rpmTag tag)
| addSource.
int | parseNoSource (rpmSpec spec, const char *field, rpmTag tag)
| parseNoSource.

## Define Documentation

#define PART_BASE 0

rpmSpec file parser states.

* Spec file parser states.

Definition at line 50 of file rpmbuild.h.

## Typedef Documentation

typedef struct OpenFileInfo OFI_t

typedef struct Package_s* Package

Definition at line 18 of file rpmspec.h.

typedef struct ReadLevelEntry RLE_t

typedef enum rpmBuildFlags_e rpmBuildFlags

Bit(s) to control buildSpec() operation.

typedef struct speclines_s * speclines

typedef struct spectag_s * spectag

typedef struct spectags_s * spectags

## Enumeration Type Documentation

enum rpmBuildFlags_e

Bit(s) to control buildSpec() operation.

Enumerator:

  RPMBUILD_NONE |
  RPMBUILD_PREP | Execute %prep.
  RPMBUILD_BUILD | Execute %build.
  RPMBUILD_INSTALL | Execute %install.
  RPMBUILD_CHECK | Execute %check.
  RPMBUILD_CLEAN | Execute %clean.
  RPMBUILD_FILECHECK | Check %files manifest.
  RPMBUILD_PACKAGESOURCE | Create source package.
  RPMBUILD_PACKAGEBINARY | Create binary package(s).
  RPMBUILD_RMSOURCE | Remove source(s) and patch(s).
  RPMBUILD_RMBUILD | Remove build sub-tree.
  RPMBUILD_STRINGBUF | only for doScript()
  RPMBUILD_RMSPEC | Remove spec file.

Definition at line 25 of file rpmbuild.h.

## Function Documentation

void addChangelogEntry | ( | Header | h,
|  | time_t | time,
|  | const char * | name,
|  | const char * | text |
| ) |  |  |

Add changelog entry to header.

Parameters:

  | h | header
  | time | time of change
  | name | person who made the change
  | text | description of change

int addReqProv | ( | rpmSpec | spec,
|  | Header | h,
|  | rpmTag | tagN,
|  | const char * | N,
|  | const char * | EVR,
|  | rpmsenseFlags | Flags,
|  | uint32_t | index |
| ) |  |  |

Add dependency to header, filtering duplicates.

Parameters:

  | spec | spec file control structure
  | h | header
  | tagN | tag, identifies type of dependency
  | N | (e.g. Requires: foo < 0:1.2-3, "foo")
  | EVR | (e.g. Requires: foo < 0:1.2-3, "0:1.2-3")
  | Flags | (e.g. Requires: foo < 0:1.2-3, both "Requires:" and "<")
  | index | (0 always)

Returns:
  0 always

int addSource | ( | rpmSpec | spec,
|  | Package | pkg,
|  | const char * | field,
|  | rpmTag | tag |
| ) |  |  |

addSource.

Parameters:

  | spec | spec file control structure
  | pkg | package control
  | field | field to parse
  | tag | tag

const char* buildHost | ( | void |  | ) |

Return build hostname.

Returns:
  build hostname

rpmRC buildSpec | ( | rpmts | ts,
|  | rpmSpec | spec,
|  | int | what,
|  | int | test |
| ) |  |  |

Build stages state machine driver.

Parameters:

  | ts | transaction set
  | spec | spec file control structure
  | what | bit(s) to enable stages of build
  | test | don't execute scripts or package if testing

Returns:
  RPMRC_OK on success

Referenced by buildForTarget().

void closeSpec | ( | rpmSpec | spec | ) |

Stop reading from spec file, freeing resources.

Parameters:

  | spec | spec file control structure

rpmRC doScript | ( | rpmSpec | spec,
|  | rpmBuildFlags | what,
|  | const char * | name,
|  | StringBuf | sb,
|  | int | test |
| ) |  |  |

Run a build script, assembled from spec file scriptlet section.

Parameters:

  | spec | spec file control structure
  | what | type of script
  | name | name of scriptlet section
  | sb | lines that compose script body
  | test | don't execute scripts or package if testing

Returns:
  RPMRC_OK on success

void freeNames | ( | void |  | ) |

Destroy uid/gid caches.

Referenced by main().

Package freePackage | ( | Package | pkg | ) |

Destroy package control structure.

Parameters:

  | pkg | package control structure

Returns:
  NULL

Package freePackages | ( | Package | packages | ) |

Destroy all packages associated with spec file.

Parameters:

  | packages | package control structure chain

Returns:
  NULL

rpmSpec freeSpec | ( | rpmSpec | spec | ) |

Destroy Spec structure.

Parameters:

  | spec | spec file control structure

Returns:
  NULL always

Referenced by buildForTarget().

rpm_time_t* getBuildTime | ( | void |  | ) |

Return build time stamp.

Returns:
  build time stamp

gid_t getGidS | ( | const char * | gname | ) |

Return cached group id.

Todo:
  Implement using hash.

Parameters:

  | gname | group name

Returns:
  cached gid

const char* getGname | ( | gid_t | gid | ) |

Return cached group name from group id.

Todo:
  Implement using hash.

Parameters:

  | gid | group id

Returns:
  cached group name

const char* getGnameS | ( | const char * | gname | ) |

Return cached group name.

Todo:
  Implement using hash.

Parameters:

  | gname | group name

Returns:
  cached group name

uid_t getUidS | ( | const char * | uname | ) |

Return cached user id.

Todo:
  Implement using hash.

Parameters:

  | uname | user name

Returns:
  cached uid

const char* getUname | ( | uid_t | uid | ) |

Return cached user name from user id.

Todo:
  Implement using hash.

Parameters:

  | uid | user id

Returns:
  cached user name

const char* getUnameS | ( | const char * | uname | ) |

Return cached user name.

Todo:
  Implement using hash.

Parameters:

  | uname | user name

Returns:
  cached user name

void handleComments | ( | char * | s | ) |

Truncate comment lines.

Parameters:

  | s | skip white space, truncate line at '#'

void initSourceHeader | ( | rpmSpec | spec | ) |

Create and initialize header for source package.

Parameters:

  | spec | spec file control structure

Referenced by buildForTarget().

rpmParseState isPart | ( | const char * | line | ) |

Check line for section separator, return next parser state.

Parameters:

  | line | from spec file

Returns:
  next parser state

rpmRC lookupPackage | ( | rpmSpec | spec,
|  | const char * | name,
|  | int | flag,
|  | Package * | pkg |
| ) |  |  |

Find sub-package control structure by name.

Parameters:

  | spec | spec file control structure
  | name | (sub-)package name
  | flag | if PART_SUBNAME, then 1st package name is prepended

Return values:

  | pkg | package control structure

Returns:
  0 on success, 1 on failure

struct OpenFileInfo* newOpenFileInfo | ( | void |  | ) | `[read]`

Package newPackage | ( | rpmSpec | spec | ) |

Create and initialize package control structure.

Parameters:

  | spec | spec file control structure

Returns:
  package control structure

rpmSpec newSpec | ( | void |  | ) |

Create and initialize rpmSpec structure.

Returns:
  spec spec file control structure

rpmRC packageBinaries | ( | rpmSpec | spec | ) |

Generate binary package(s).

Parameters:

  | spec | spec file control structure

Returns:
  RPMRC_OK on success

rpmRC packageSources | ( | rpmSpec | spec | ) |

Generate source package.

Parameters:

  | spec | spec file control structure

Returns:
  RPMRC_OK on success

int parseBuildInstallClean | ( | rpmSpec | spec,
|  | rpmParseState | parsePart |
| ) |  |  |

Parse %build/%install/%clean section(s) of a spec file.

Parameters:

  | spec | spec file control structure
  | parsePart | current rpmParseState

Returns:
  >= 0 next rpmParseState, < 0 on error

int parseChangelog | ( | rpmSpec | spec | ) |

Parse %changelog section of a spec file.

Parameters:

  | spec | spec file control structure

Returns:
  >= 0 next rpmParseState, < 0 on error

int parseDescription | ( | rpmSpec | spec | ) |

Parse %description section of a spec file.

Parameters:

  | spec | spec file control structure

Returns:
  >= 0 next rpmParseState, < 0 on error

int parseExpressionBoolean | ( | rpmSpec | spec,
|  | const char * | expr |
| ) |  |  |

Evaluate boolean expression.

Parameters:

  | spec | spec file control structure
  | expr | expression to parse

Returns:

char* parseExpressionString | ( | rpmSpec | spec,
|  | const char * | expr |
| ) |  |  |

Evaluate string expression.

Parameters:

  | spec | spec file control structure
  | expr | expression to parse

Returns:

int parseFiles | ( | rpmSpec | spec | ) |

Parse %files section of a spec file.

Parameters:

  | spec | spec file control structure

Returns:
  >= 0 next rpmParseState, < 0 on error

int parseNoSource | ( | rpmSpec | spec,
|  | const char * | field,
|  | rpmTag | tag |
| ) |  |  |

parseNoSource.

Parameters:

  | spec | spec file control structure
  | field | field to parse
  | tag | tag

int parsePreamble | ( | rpmSpec | spec,
|  | int | initialPackage |
| ) |  |  |

Parse tags from preamble of a spec file.

Parameters:

  | spec | spec file control structure
  | initialPackage |

Returns:
  >= 0 next rpmParseState, < 0 on error

int parsePrep | ( | rpmSpec | spec | ) |

Parse %prep section of a spec file.

Parameters:

  | spec | spec file control structure

Returns:
  >= 0 next rpmParseState, < 0 on error

rpmRC parseRCPOT | ( | rpmSpec | spec,
|  | Package | pkg,
|  | const char * | field,
|  | rpmTag | tagN,
|  | int | index,
|  | rpmsenseFlags | tagflags |
| ) |  |  |

Parse dependency relations from spec file and/or autogenerated output buffer.

Parameters:

  | spec | spec file control structure
  | pkg | package control structure
  | field | text to parse (e.g. "foo < 0:1.2-3, bar = 5:6.7")
  | tagN | tag, identifies type of dependency
  | index | (0 always)
  | tagflags | dependency flags already known from context

Returns:
  RPMRC_OK on success, RPMRC_FAIL on failure

int parseScript | ( | rpmSpec | spec,
|  | int | parsePart |
| ) |  |  |

Parse %pre et al scriptlets from a spec file.

Parameters:

  | spec | spec file control structure
  | parsePart | current rpmParseState

Returns:
  >= 0 next rpmParseState, < 0 on error

int parseSpec | ( | rpmts | ts,
|  | const char * | specFile,
|  | const char * | rootDir,
|  | const char * | buildRoot,
|  | int | recursing,
|  | const char * | passPhrase,
|  | const char * | cookie,
|  | int | anyarch,
|  | int | force |
| ) |  |  |

Parse spec file into spec control structure.

Parameters:

  | ts | transaction set (spec file control in ts->spec)
  | specFile |
  | rootDir |
  | buildRoot |
  | recursing | parse is recursive?
  | passPhrase |
  | cookie |
  | anyarch |
  | force |

Returns:

Referenced by buildForTarget().

uint32_t parseUnsignedNum | ( | const char * | line,
|  | uint32_t * | res |
| ) |  |  |

Parse an unsigned number.

Parameters:

  | line | from spec file

Return values:

  | res | pointer to uint32_t

Returns:
  0 on success, 1 on failure

int processBinaryFiles | ( | rpmSpec | spec,
|  | int | installSpecialDoc,
|  | int | test |
| ) |  |  |

Post-build processing for binary package(s).

Parameters:

  | spec | spec file control structure
  | installSpecialDoc |
  | test | don't execute scripts or package if testing

Returns:
  0 on success

int processSourceFiles | ( | rpmSpec | spec | ) |

Post-build processing for source package.

Parameters:

  | spec | spec file control structure

Returns:
  0 on success

int readLine | ( | rpmSpec | spec,
|  | int | strip |
| ) |  |  |

Read next line from spec file.

Parameters:

  | spec | spec file control structure
  | strip | truncate comments?

Returns:
  0 on success, 1 on EOF, <0 on error

int rpmlibNeedsFeature | ( | Header | h,
|  | const char * | feature,
|  | const char * | featureEVR |
| ) |  |  |

Add rpmlib feature dependency.

Parameters:

  | h | header
  | feature | rpm feature name (i.e. "rpmlib(Foo)" for feature Foo)
  | featureEVR | rpm feature epoch/version/release

Returns:
  0 always

int rpmspecQuery | ( | rpmts | ts,
|  | QVA_t | qva,
|  | const char * | arg |
| ) |  |  |

Function to query spec file(s).

Parameters:

  | ts | transaction set
  | qva | parsed query/verify options
  | arg | query argument

Returns:
  0 on success, else no. of failures

Referenced by main().

spectag stashSt | ( | rpmSpec | spec,
|  | Header | h,
|  | rpmTag | tag,
|  | const char * | lang |
| ) |  |  |

stashSt.

Parameters:

  | spec | spec file control structure
  | h | header
  | tag | tag
  | lang | locale