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-88f6281

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 88f6281;

  • To list all available architectures use ls toolchains 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(s). 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;

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

  • cd spksrc/cross/newpackage/;
  • make arch-88f6281;
  • Use make clean to clean up the whole working directory after a failed attempt.

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.
• Create a digests file with make digests for every new or updated cross package.

The next step is to create the SPK itself:

• Copy a standard SPK directory like spksrc/spk/transmission; in 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.

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 at least make arch-x64-6.1 arch-aarch64-6.1 to confirm cross-compilation for recent ARMv8 platforms
• Look for make output Stripping ... failed! because of invalid directives in PLIST files
• Custom targets follow naming convention package_original_target for instance tree_install_target
• 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.