Docs

Rules

info_file
maintainer
privilege_config
protocol_file
resource_config
service_config
usr_local_linker

Functions

confirm_binary_matches_platform
images

info_file

load("@rules_synology//:defs.bzl", "info_file")

info_file(name, out, arch_strings, description, maintainer, os_min_ver, package_name,
          package_version)

Create an INFO file

The INFO file is the simple metadata k/v dict of the SPK: a number of key=value pairs that define attributes of the package.

This file is needed to inform the Synology NAS of the name and unique ID of the package, quote maintainers and distributors, and indicate architecture and OS constraints to install. I personally expect that the simple format of this file allows the UI to show install dialogs with minimal complexity.

Likely the reader will notice that the maintainer() block collects more information than it needs to for the INFO file: the additional URL is optional, but can help track down a maintainer if a user or collaborator needs to find them. This is not necessarily intended to be the upstream URL(s) of a project (ie github pages, docker URLs,etc) but is intended to be a valid URL that can help precisely identify where the preferred path to find that maintainer.

This implementation mimics the defaults from Synology's documentation so that the bare minimum attributes can be provided to unblock immediate progress.

Examples

(BUILD file)

load("@rules_synology//:defs.bzl", "info_file", "maintainer")

maintainer(
    name = "chickenandpork",
    maintainer_name = "Allan Clark",
    maintainer_url = "http://linkedin.com/in/goldfish",
    visibility = ["//visibility:public"],
)

info_file(
    name = "floppydog_info",
    package_name = "FloppyDog",
    description = "Provides the FloppyDog set of CLI tools for Great Justice",
    maintainer = ":chickenandpork",
    os_min_ver = "7.0-1",  # correct-format=[^\d+(\.\d+){1,2}(-\d+){1,2}$]
    package_version = "1.0.0-1",
)

The INFO file generated by this looks similar to:

package="FloppyDog"
version="1.0.0-1"
os_min_ver="7.0-1"
description="Provides the FloppyDog set of CLI tools for Great Justice"
maintainer="Allan Clark"
arch="noarch"
thirdparty="yes"

info_file() uses maintainer() to carry information about the package's maintainer: referring to a maintainer by target ID allows greatest re-use of a DRY data element, and should allow the author to associate a maintainer globally maintained in a dependency resource:

(MODULE.bazel)

bazel_dep(name = "firehydrant_stuff", version = "1.2.3")

(BUILD.bazel)

info_file(
    name = "firehydrant_info",
    package_name = "FireHydrant",
    description = "A great Incident-Management resource made by SREs for SREs",
    maintainer = "@firehydrant_stuff//maint:robertross",
    os_min_ver = "7.0-1",  # correct-format=[^\d+(\.\d+){1,2}(-\d+){1,2}$]
    package_version = "1.0.0-1",
)

Ref: * Synology: INFO

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
out	Name of the Info file, if INFO is not preferred (changing this is not recommended).	Label	optional	`None`
arch_strings	array of architectures (strings): [ "alpine", ...] (default: ["noarch"]).	List of strings	optional	`["noarch"]`
description	Brief description of the package: copy-paste from the upstream if permissible. Although this is permitted be a looooong single-line string, it does display on the UIs to install a package, so brevity is still encouraged.	String	required
maintainer	Maintainer of the build logic for the component (primary if multiple, a person)	Label	required
os_min_ver	Earliest version of DSM that can install the package; ie "DSM 7.1.1-42962". There seems to be no handling of the extended hard-to-parse suffixes used by Synology such as "DSM 7.1.1-42962 Update 6".	String	required
package_name	Name of the package, unique within Synology SPKs, hopefully resembles external package name	String	required
package_version	Version of the package; although I recommend semver-ish X.Y.Z-BUILDNUM, Synology describes as being any string of numbers separated by periods, dash, or underscore	String	required

maintainer

load("@rules_synology//:defs.bzl", "maintainer")

maintainer(name, maintainer_name, maintainer_url)

A simple wrapper for re-use and typing, this produces a Maintainer that can be used as an attribute to targets they maintain.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
maintainer_name	-	String	required
maintainer_url	-	String	optional	`""`

privilege_config

load("@rules_synology//:defs.bzl", "privilege_config")

privilege_config(name, out, run_as_package, run_as_root)

A function (currently stubbed) to define a privilege configuration (conf/privilege) configuring packages installed in Synology.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
out	-	Label	optional	`None`
run_as_package	-	List of strings	optional	`[]`
run_as_root	-	List of strings	optional	`[]`

protocol_file

load("@rules_synology//:defs.bzl", "protocol_file")

protocol_file(name, out, package_name, service_config)

The Protocol file is used as a wrapper/collector of service_configs: a building-block to generate the actual file as a buildable object for use in a Port Config resource. Format is an INI file, as discussed in the DSM_Developer_Guide_7_enu.pdf, section "Port" on p 128 in my copy (search for "Configure Format Template"). Effectively, it builds the file that is pointed-to by a port-config.protocol-file entry in a resource JSON file.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
out	-	Label	optional	`None`
package_name	-	String	optional	`""`
service_config	-	List of labels	optional	`[]`

resource_config

load("@rules_synology//:defs.bzl", "resource_config")

resource_config(name, resources, out)

A function to define a resource configuration (conf/resource) configuring packages installed in Synology.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
resources	-	List of labels	required
out	-	Label	optional	`None`

service_config

load("@rules_synology//:defs.bzl", "service_config")

service_config(name, description, dst_ports, port_forward, src_ports, title)

A function to define a service configuration (port-forward) for a package installed on Synology

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
description	-	String	required
dst_ports	-	String	required
port_forward	-	Boolean	optional	`True`
src_ports	-	String	optional	`""`
title	-	String	required

usr_local_linker

load("@rules_synology//:defs.bzl", "usr_local_linker")

usr_local_linker(name, bin, etc, lib)

Configure a /usr/local Linker

The /usr/local linker is a Worker that softlinks payload binaries, libraries, and config files to bin, lib, and etc subdirectories in /usr/local on package start and removes on package stop. If the link or file pre-exists, /usr/local worker will unlink() those files, effectively overwriting. Any failure to pre-delete or create a link results in the process failing, triggering any rollback.

Example

This will cause a softlink to be created in /usr/local/bin that points to /var/packages/<package>/target/bin/netfilter-mods:

load("@rules_synology//:defs.bzl", "usr_local_linker")

usr_local_linker(
    name = "softlinks",
    bin = ["netfilter-mods"],
)

There is currently no method of linking to a target with a different name: the underlying config that Synology doesn't offer that capability.

Ref: * Synology: /usr/local linker

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
bin	binary paths to softlink into /usr/local/bin	List of strings	optional	`[]`
etc	configfile paths to softlink into /usr/local/etc	List of strings	optional	`[]`
lib	library paths to softlink into /usr/local/lib	List of strings	optional	`[]`

confirm_binary_matches_platform

load("@rules_synology//:defs.bzl", "confirm_binary_matches_platform")

confirm_binary_matches_platform(binary)

PARAMETERS

Name	Description	Default Value
binary	-	none

images

load("@rules_synology//:defs.bzl", "images")

images(name, src)

PARAMETERS

Name	Description	Default Value
name	-	`"images"`
src	-	`":PACKAGE_ICON.PNG"`