npm-pkgbuild

npm-pkgbuild

Create ArchLinux, RPM, Debian and Docker packages from npm packages.

usage

In a package directory execute

npm-pkgbuild --rpm --debian --arch --content /destination:build --publish /some/directory

This will create a arch, rpm and a debian package of the build dir.

upload package

npm-pkgbuild --arch --content build --publish 'https://my.package-service.com/binaries/linux/{{type}}/{{access}}/{{arch}}'

You can specify the package content in package.json.

{
  "pkgbuild": {
    "content": {
      "/some/location/" : { "base": "build" },
      "/etc/myconfig.json" : "sample-config.json",
      "/erc/secret" : { "name":  "secret", "mode": "600" },
      "/opt/myapp": [
        {
          "type": "npm-pack"
        },
        {
          "type": "node-modules",
          "withoutDevelpmentDependencies": true
        }
      ]
    },
    "hooks" : "pkg/hooks",
    "output": {
      "debian" : {},
      "rpm" : {},
      "arch" : {}
    },
  "dependencies": { "nginx" : ">=1.12" }
  }
}

content providers

Defining where the package content should come from.

files (default)

content from the file system

npm-pack

content as provided by npm pack

node-modules

content of all (production) dependencies

options: - withoutDevelpmentDependencies when to stip away dev dependencies (defaults to true)

shared configuration

You can import common configuration from other packages. See mf-hosting or mf-hosting-frontend modules.

API

Table of Contents

• allInputs
• allOutputs
• npmArchMapping
• content2Sources
  • Parameters
• PackageDefinition
  • Properties
• extractFromPackage
  • Parameters
• NPMPackContentProvider
  • Parameters
  • Properties
  • name
• NodeModulesContentProvider
  • Parameters
  • Properties
  • name
• FileContentProvider
  • Parameters
  • asyncIterator
  • name
• NFTContentProvider
  • Parameters
  • asyncIterator
  • name
• ContentProvider
  • Parameters
  • Properties
  • asyncIterator
• DEBIAN
  • hookMapping
  • prepare
    • Parameters
• fields
• fields
• fields
• fields
• pkgKeyValuePairOptions
• quoteFile
  • Parameters
• RPM
  • hookMapping
  • prepare
    • Parameters
• OCI
• DOCKER
  • prepare
    • Parameters
• BUILDAH
• Packager
  • Parameters
  • packageName
    • Parameters
  • tmpdir
  • prepare
    • Parameters
  • create
    • Parameters
  • workspaceLayout
  • prepare
    • Parameters
• Packager
  • Parameters
  • packageName
    • Parameters
  • tmpdir
  • prepare
    • Parameters
  • create
    • Parameters
  • workspaceLayout
  • prepare
    • Parameters
• Field
  • Properties
• copyNodeModules
  • Parameters
• PublishingDetail
  • Properties
• createPublishingDetails
  • Parameters
• publish
  • Parameters
• utf8StreamOptions
• decodePassword
  • Parameters
• FunctionDecl
  • Properties
• extractFunctions
  • Parameters
• fieldProvider
  • Parameters
• Expander
  • Parameters
• copyEntries
  • Parameters

allInputs

All content providers (input)

allOutputs

All output formats

npmArchMapping

Node architecture name to os native arch name mapping {@see https://nodejs.org/dist/latest-v18.x/docs/api/process.html#processargv}

content2Sources

Delivers ContentProviders from pkgbuild.content definition.

Parameters

• content Object from pkgbuild.content
• dir

Returns Iterable<ContentProvider>

PackageDefinition

Type: Object

Properties

• properties Object values describing the package attributes

  • properties.dependencies Object

• sources Array<ContentProvider> content providers

• output Object package type

• variant Object identifier of the variant

  • variant.name string name of the variant
  • variant.arch string name of the architecture

extractFromPackage

Extract package definition from package.json.

• for each architecture deliver a new result
• if no architecture is given one result set is provided nethertheless
• architectures are taken from cpu (node arch ids) and from pkgbuild.arch (raw arch ids)
• architecture given in a variant definition are used to restrict the set of avaliable architectures

Parameters

• options Object (optional, default {})

  • options.dir string? where to look for package.json
  • options.verbose boolean? log

• env Object as delared in process.env (optional, default {})

Returns AsyncIterable<PackageDefinition>

NPMPackContentProvider

Extends ContentProvider

Content from npm pack.

Parameters

• definitions Object
• entryProperties Object to be set for each entry
• directoryProperties

Properties

• dir string

name

Returns string name of the content provider

NodeModulesContentProvider

Extends ContentProvider

Content from node_modules. Requires .npmrc or NPM_TOKEN environment

Parameters

• definitions
• entryProperties
• directoryProperties

Properties

• withoutDevelpmentDependencies boolean

name

Returns string name of the content provider

FileContentProvider

Extends ContentProvider

Content provided form the file system.

Parameters

• definitions (Object | string)

  • definitions.pattern (string | Array<string>)
  • definitions.base string base directory where to find the files

• entryProperties

• directoryProperties

asyncIterator

Returns AsyncIterable<ContentEntry> all entries

name

Returns string name of the content provider

NFTContentProvider

Extends ContentProvider

Content provided form the file system.

Parameters

• definitions (Object | string)

  • definitions.pattern (string | Array<string>)
  • definitions.base string base directory where to find the files

• entryProperties

• directoryProperties

asyncIterator

Returns AsyncIterable<ContentEntry> all entries

name

Returns string name of the content provider

ContentProvider

Source of package content.

Parameters

• definitions
• entryProperties
• directoryProperties

Properties

• dir string
• transformer Array<Transformer>

asyncIterator

List all entries.

Returns AsyncIterable<ContentEntry> all entries

DEBIAN

Extends Packager

Create .deb packages

hookMapping

Map install hook named from default (arch) to deb.

prepare

Parameters

• options Object

• variant Object

  • variant.arch string

Returns Promise<boolean>

fields

• See: https://www.debian.org/doc/debian-policy/ch-controlfields.html
• See: https://linux.die.net/man/5/deb-control

fields

well known package properties https://www.archlinux.org/pacman/PKGBUILD.5.html

fields

• See: https://rpm-packaging-guide.github.io

fields

• See: https://docs.docker.com/engine/reference/builder/

pkgKeyValuePairOptions

Type: Object

quoteFile

Parameters

• name

RPM

Extends Packager

Produce rpm packages.

hookMapping

Map install hook named from default (arch) to rpm.

prepare

Check for rpmbuild presence.

Parameters

• options Object

• variant Object

  • variant.arch string

Returns Promise<boolean> true when rpmbuild executable is present

OCI

Extends Packager

Low level OCI compatible packager

DOCKER

Extends Packager

docker image build

prepare

Check for docker presence.

Parameters

• options Object

• variant Object

  • variant.arch string

Returns Promise<boolean> true when docker executable is present

BUILDAH

Extends DOCKER

Use buildah @see https://buildah.io

Packager

Parameters

• properties

packageName

What is the package name in the package eco-system.

Parameters

• name string

Returns string package name in the target eco-system

tmpdir

Create tmp directory.

Returns Promise<string> directory path

prepare

Prepares artifact generation.

Parameters

• options Object
• publishingDetail Object?

Returns Promise<{properties: Object, destination: string, tmpdir: string, staging: string}>

create

Execute package generation.

Parameters

• sources Object
• transformer Array<Object>
• publishingDetails Array<PublishingDetail>
• options Object
• expander function (string): string?

Returns Promise<string> identifier of the resulting package

workspaceLayout

Returns {named: object, others: Array<string>}

prepare

Parameters

• options Object
• variant Object

Returns Promise<boolean>

Packager

Base Packager

Parameters

• properties Object

packageName

What is the package name in the package eco-system.

Parameters

• name string

Returns string package name in the target eco-system

tmpdir

Create tmp directory.

Returns Promise<string> directory path

prepare

Prepares artifact generation.

Parameters

• options Object
• publishingDetail Object?

Returns Promise<{properties: Object, destination: string, tmpdir: string, staging: string}>

create

Execute package generation.

Parameters

• sources Object
• transformer Array<Object>
• publishingDetails Array<PublishingDetail>
• options Object
• expander function (string): string?

Returns Promise<string> identifier of the resulting package

workspaceLayout

Returns {named: object, others: Array<string>}

prepare

Parameters

• options Object
• variant Object

Returns Promise<boolean>

Field

Type: Object

Properties

• alias string interchangeable field name
• type string
• default any
• mandatory boolean

copyNodeModules

Parameters

• source string
• dest string
• options Object (optional, default defaultOptions)

PublishingDetail

Type: Object

Properties

• url string
• properties Object
• scheme string
• username string?
• password string?

createPublishingDetails

Parameters

• locations Array<string> (optional, default [])

• properties Object?

  • properties.PKGBUILD_PUBLISH string?
  • properties.arch string?
  • properties.access string?
  • properties.type string?
  • properties.username string?

Returns Array<PublishingDetail>

publish

Parameters

• artifactIdentifier string
• publishingDetail PublishingDetail?
• properties Object?
• logger function (any): void (optional, default console.log)

utf8StreamOptions

Type: BufferEncoding

decodePassword

Decode a password

Parameters

• password string

Returns string plaintext password

FunctionDecl

Type: Object

Properties

• name string
• body string

extractFunctions

Extract shell functions from a given text.

Parameters

• source AsyncIterable<string>

Returns AsyncIterable<FunctionDecl>

fieldProvider

Parameters

• properties Object
• fields Object

Returns Function

Expander

Type: Function

Parameters

• path string

Returns string

copyEntries

Copy content from source into destinationDirectory. Destination paths a generated without leading '/' (as for entry names too).

Parameters

• source AsyncIterable<ContentEntry>
• destinationDirectory string
• expander Expander (optional, default v=>v)

install

With npm do:

npm install npm-pkgbuild

license

BSD-2-Clause