From b76ef096d4aba66cbbd884a5f53b012c5ba0351c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karel=20Ko=C4=8D=C3=AD?= Date: Fri, 2 Feb 2018 00:21:13 +0100 Subject: Add readme and generate_keys.sh script --- README.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..ee7f793 --- /dev/null +++ b/README.md @@ -0,0 +1,187 @@ +Turris repository builder +========================= +This implements simple script that alows you to build additional packages for +Turris routers. Idea is that you can use this to create either permanent or +testing builds. + +You have to use machine with amd64 architecture and GNU and Linux base +distribution because this tool uses precompiled OpenWRT SDK that was compiled on +such machine and won't work on any other architecture. Also you need dependencies +as for standard OpenWRT build (those can be found in OpenWRT documentation). On +top of that a ccache was used on original build machine so you have to have it +installed too. + +Before first usage +------------------ +Before first usage you have to create package that is going to define your +repository. This will give you an easy way to install your repository on router. +Let's create package `myrepo` for this (of course you should name it some more +appropriate way). First create directory names `myrepo` and then `Makefile` file +inside it. That `Makefile` should contain something like this: +```Makefile +include $(TOPDIR)/rules.mk + +PKG_NAME:= +PKG_VERSION:=1 +PKG_MAINTAINER:= +PKG_BUILD_DIR:=$(BUILD_DIR)/$(PKG_NAME) + +include $(INCLUDE_DIR)/package.mk + +define Package/myrepo + TITLE:=$(PKG_NAME) +endef + +define Build/Compile + : +endef + +define Package/$(PKG_NAME)/install + $(INSTALL_DIR) $(1)/etc/updater/keys + $(INSTALL_DATA) ./files/key.pub $(1)/etc/updater/keys/$(PKG_NAME).pub + + $(INSTALL_DIR) $(1)/etc/updater/conf.d + $(INSTALL_CONF) ./files/updater.lua $(1)/etc/updater/conf.d/$(PKG_NAME).lua +endef + +$(eval $(call BuildPackage,$(PKG_NAME))) +``` +We will return to this `Makefile` later on. Now we need to create directory +`files` containing public key and configuration for updater-ng. Let's start with +updater's configuration. We want to write it to file named `updater.lua` because +that is name we have in `Makefile`. The content should be something like this: +```Lua +local board +if model:match('[Oo]mnia') then + board = "omnia" +else + board = "turris" +end +Repository("", "https://unknown.com/" .. board .. "/", { + pubkey = "file:///etc/updater/keys/.pub" +}) +Install("") +Package("", { replan = "finished" }) +``` +Of course replace `` with your chosen name and `unknown.com` with +real address where you plan host your repository. This tells updater where it can +found your repository. There is possibility that you want to disable some security +features such as OCSP or specify CRL file. For that you should look at [updater's +documentation](https://turris.pages.labs.nic.cz/updater/). + +Now let's look to keys. For simplicity you can use `generate_keys.sh` script that +is in repository it self. It uses program called usign and to compile it you need +cmake on top of OpenWRT SDK dependencies. This script will generate two files for +you: `key.pub` and `key.sec`. Move `key.pub` to `files` directory of your +repository package and let `key.sec` in current working directory. + +Now you can go back to `Makefile`. Make sure that all `` strings +are correctly replaced with name you desire and that you have filled in your name +and email as a maintainer of that package. + +Latest thing that you want optionally do is to create your own script calling +`build_repo.sh` script and then immediately uploading repository to your server. + +Now you should be ready to do first testing build. This build should build package +you have just created. You can run `build_repo.sh` script in directory where you +have directory with your new repository package and with `key.sec` file. If +everything went well then you should have directory named `repo` in your working +directory containing opkg repository with your new package. + +_todo: We should probably also configure opkg._ + +Usage +----- +To build some package you have to place it to directory where you have your +`key.sec`. It can't be in some subdirectory because script `build_repo.sh` handles +only top level directories that contains file `Makefile` as packages. When you +have it there then you can just run `build_repo.sh` in that top level directory. +When script exits you should have directory `repo` with your new repository. + +If build for some reason failed then you can run `build_repo.sh` with arguments +`-j1 V=99` to see exactly what went wrong. + +In default `build_repo.sh` builds repository for Turris Omnia. You can specify +`turris` as first argument (has to be before `-j1` for example) to build packages +for Turris 1.x. Or you can specify `all` to build both. Just to completeness +script also accepts `omnia` as first argument to build for Turris Omnia (default +behavior). + +If you need some changes to configuration (such as enable/disable some additional +features for OpenWRT) then you can also create file `CONFIG` in top level +directory of your myrepo directory. Content of this file is appended to `.config` +in sdk and that way is used during build. But be aware that using `CONFIG` can +potentially cause rebuild of packages you haven't provided and you can end up with +dependency nightmare. + +Always building latest commit +----------------------------- +As part of this repository is also a highly experimental pkgauto.mk extension. +This is deployed to common include paths of packages and allows you to always +build top most commit in specified branch. This is very handy for development +purposes. + +Only supported protocol is git. + +To use this you have to first define `PKG_NAME`, `PKG_SOURCE_URL` and +`PKG_SOURCE_BRANCH` variables (same as for any other OpenWRT package). Afterwards +you have to include file `$(INCLUDE_DIR)/pkgauto.mk`. This file will clone +repository specified by `PKG_SOURCE_URL` to directory `.pkgauto` in current +working directory. From this the variables `PKG_SOURCE_VERSION`, `PKG_VERSION` and +`PKG_RELEASE` are deduced as follows: + +* `PKG_SOURCE_VERSION`: This is filed in with hash of latest commit from + `PKG_SOURCE_BRANCH` branch. +* `PKG_VERSION`: This look for latest version tag on specified branch. Version + tags are understood as all tags starting with `v`. `v` is cut off and rest is + considered as base version for this package. To ensure that this package will + always be preferred no matter on `PKG_RELEASE` it also appends `.9999`. If it + locates no such commit then it uses `9999` as `PKG_VERSION` and fills + `PKG_RELEASE` with number of commit since initial commit. +* `PKG_RELEASE`: This is fill with number of commit since `PKG_VERSION`. To + understand this more read description for `PKG_VERSION`. + +On top of these variables it also defines some less dynamic variables. Following +variables are defined with specified values: +```Makefile +PKG_SOURCE:=$(PKG_NAME)-$(PKG_SOURCE_VERSION).tar.gz +PKG_SOURCE_SUBDIR:=$(PKG_NAME) +PKG_BUILD_DIR:=$(BUILD_DIR)/$(PKG_NAME) +HOST_BUILD_DIR:=$(BUILD_DIR_HOST)/$(PKG_NAME) +``` + +To give some example here is head of python3-periphery package Makefile with +explicit version: +```Makefile +include $(TOPDIR)/rules.mk + +PKG_NAME:=python3-periphery +PKG_VERSION:=v1.1.0 +PKG_RELEASE:=1 +PKG_LICENSE:=MIT + +PKG_SOURCE_PROTO:=git +PKG_SOURCE_URL:=https://github.com/vsergeev/python-periphery.git +PKG_SOURCE_VERSION:=$(PKG_VERSION) +PKG_SOURCE_SUBDIR:=$(PKG_NAME)-$(PKG_VERSION) +PKG_SOURCE:=$(PKG_NAME)-$(PKG_SOURCE_VERSION).tar.gz +PKG_BUILD_DIR:=$(BUILD_DIR)/$(PKG_NAME)-$(PKG_VERSION) + +include $(INCLUDE_DIR)/package.mk +$(call include_mk, python3-package.mk) +``` +And here is same package with `pkgauto.mk` used: +```Makefile +include $(TOPDIR)/rules.mk + +PKG_NAME:=python3-periphery +PKG_LICENSE:=MIT + +PKG_SOURCE_PROTO:=git +PKG_SOURCE_URL:=https://github.com/vsergeev/python-periphery.git +PKG_SOURCE_BRANCH:=HEAD + +include $(INCLUDE_DIR)/pkgauto.mk +include $(INCLUDE_DIR)/package.mk +$(call include_mk, python3-package.mk) +``` -- cgit v1.2.3