Developers HOW TO

Getting started with spksrc

Setup a development environment

See Set up the development environment in the README.

Build a package

Let's start with building the Transmission package from start to finish:

git clone https://github.com/SynoCommunity/spksrc.git
cd spksrc/
make setup
cd spk/transmission
make arch-aarch64-7.0

There are alternatives to this command to run a build.

What have I done?

• You cloned the repository;

• Created a settings file with make setup;

• Went into the directory of the SPK for transmission;

• Started building the SPK for the architecture aarch64 on DSM 7.0;

  • To list all available architectures use ls toolchain from within the spksrc directory. Remove the prefix syno- to have the actual architecture.
  • An overview of which architecture is used per Synology model can be found on the wiki page Architecture per Synology model.

At the end of the process, the SPK will be available in spksrc/packages/.

What is spksrc doing?

• First spksrc will read spksrc/spk/transmission/Makefile;

• Download the adequate toolchain for the chosen architecture;

• Recursively:

  • Process dependencies if any;
  • Download the source in spksrc/distrib/;
  • Extract the source;
  • configure;
  • make;
  • make install.

• Package all the requirements into a SPK under spksrc/packages/:

  • Binaries;
  • Installer script;
  • Start/Stop/Status script;
  • Package icon;
  • Help files (optional);
  • Resource files (optional);
  • Service configure file (optional);
  • Wizards (optional);

Create a package

Creating an SPK usually starts with cross-compiling the underlying package and its dependencies. To do so, you can copy an existing Makefile from another package. For example:

• Copy a standard cross package like spksrc/cross/transmission/Makefile in your new package directory spksrc/cross/newpackage/;

• Edit the Makefile variables so it fits your new package;

• Empty variables DEPENDS and CONFIGURE_ARGS in the Makefile;

• Create the digests file with make digests to verify the download link and create the digests file with file hashes to validate the file content (call make clean before calling make digests again after failed downloads).

• Create a digests file for every new or updated cross package.

• Try to cross-compile and fix issues as they come (missing dependencies, configure arguments, patches):

  • cd spksrc/cross/newpackage/;
  • make arch-x64-7.1;
  • Use make clean to clean up the whole working directory after a failed attempt.
  • Compile for any arm arch to validate cross compilation.
  • make arch-armv7-7.1;

Once you have been able to successfully cross-compile the package:

• Create a PLIST file with the same syntax as spksrc/cross/transmission/PLIST but based on the auto-generated PLIST for your new package at spksrc/cross/newpackage/work-88f6281/newpackage.plist;

  • For more background, see PLIST files.

• Compile for all supported processor architectures:

  • make all-supported;

• Define incompatible archs with UNSUPPORTED_ARCHS (optinal) and document the reason for it.

The next step is to create the SPK itself:

• Copy a standard SPK directory like spksrc/spk/transmission; into your new SPK directory spksrc/spk/newspk;
• Edit the Makefile so it fits the new SPK;
• Build and test to make sure the package works. Take into consideration that package updates should work correctly.
  • Install your package via sudo synopkg install <path to .spk file (packages/newspk_ARCH-OS_...)>

Some helpful links for developing packages:

• Compile and build rules
• Makefile variables
• PLIST files
• SynoCommunity Used Ports
• Synology Used Ports
• UI Develop
• Using Wheels to distribute Python packages

Contribute to spksrc

After all that hard work, you should submit a pull request to have your work merged with the main repository on GitHub and published in SynoCommunity's repository.

Contribution Checklist

To be confident your contribution will be accepted

• Successfully build for current archs with make all-supported.
• Look for make output Stripping ... failed! because of invalid directives in PLIST files
• Custom targets follow naming convention INSTALL_TARGET = newpackage_install
• Any useless elements (files, variables, targets) from previous trials have been cleaned

For small changes (bugfixes, small new features, ...)

Make changes directly in the master branch as follows:

• Clone spksrc git clone https://github.com/SynoCommunity/spksrc.git if not done already;
• Make sure your local clone is up-to-date: git pull;
• Run make setup to create a local configuration file;
• Do stuff...
• Once you're happy with your changes, continue with Merging with spksrc to get your changes merged with spksrc.

For medium to large changes (new SPKs, new features, ...)

Create a feature branch as follows:

• Clone spksrc git clone https://github.com/SynoCommunity/spksrc.git if not done already;
• Run make setup to create a local configuration file;
• Create a new branch: git checkout -b newfeature;
• Do stuff...
• Once you're happy with your changes, continue with Merging with spksrc to get your changes merged with spksrc.

Merging with spksrc

If you are not a member of SynoCommunity

Update your remote branch, and open a Pull Request:

• Push your changes to your remote repository with git push;
• Open a Pull Request and use the template to tell us what you've created;
• We'll review the PR, and once accepted, merge your PR into master.

If you are a member of SynoCommunity

Merge with master and push

• Go back in master branch: git checkout master;
• Make sure your local clone is up-to-date: git pull;
• Merge your new feature branch with master: git merge newfeature;
• Push local master to remote: git push.

If you are not familiar with git or GitHub, please refer to the excellent GitHub help pages.

Updating & Testing the default Docker image

The following expect you are running from a Debian/Ubuntu host and not from within a Docker image. Also it is expected that youhave cloned the spksrc repository and created a new development branch.

You will find the Dockerfile under the main spksrc directory. Once you have changed the file to meet your needs you can now generate an updated docker image (may need $ sudo usermod -aG docker $USER for proper user permissions):

$ docker build - < Dockerfile
...bash
Successfully built 882a0451f1bb

You can now access the docker image:

$ docker run -it -v $(pwd):/spksrc 882a0451f1bb /bin/bash

As an example you can build a python310 package or what ever you are interested at testing:

root@2ff602f23b71:/spksrc# cd spk/python310
root@2ff602f23b71:/spksrc/spk/python310/# make all-supported

(OPTIONAL) For removing all docker images afterwards:

$ docker container rm -f $(docker container ls -aq)