From 071b690ba7812f0d596c0aafdd67136b01d7b515 Mon Sep 17 00:00:00 2001 From: rubo77 Date: Thu, 8 Jun 2017 14:03:21 +0200 Subject: [PATCH 1/6] Docs: set your editor to show tabs as two spaces --- docs/dev/basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst index 2f4d1d89..0d0e0cd0 100644 --- a/docs/dev/basics.rst +++ b/docs/dev/basics.rst @@ -61,5 +61,5 @@ Code formatting may sound like a topic for the pedantic, however it helps if the code in the project is formatted in the same way. The following rules apply: -- use tabs instead of spaces +- use tabs instead of spaces (set your editor to show tabs as two spaces) - trailing whitespaces must be eliminated From c4ca11c28887299f6ea548f60715bb404918afe4 Mon Sep 17 00:00:00 2001 From: rubo77 Date: Thu, 8 Jun 2017 14:03:40 +0200 Subject: [PATCH 2/6] Docs: Upgrading Packages from 2016.2.x --- docs/dev/basics.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst index 0d0e0cd0..eecaa142 100644 --- a/docs/dev/basics.rst +++ b/docs/dev/basics.rst @@ -50,6 +50,7 @@ commits, making `git reflog` the only way to recover them! Development Guidelines ---------------------- + lua should be used instead of sh whenever sensible. The following criteria should be considered: @@ -63,3 +64,32 @@ apply: - use tabs instead of spaces (set your editor to show tabs as two spaces) - trailing whitespaces must be eliminated + +Upgrading Packages from 2016.2.x +-------------------------------- + +The site.conf and external packages to be rewritten in some parts and Gluon now +doesn't use LuCI for its Config Mode anymore, but our own fork +"gluon-web", which is significantly smaller (as lots of features we don't +need have been removed) for detailed changes see `/dev/web/`_. + +.. _/dev/web/: + +- the function ``gluon_luci.escape()`` must be replaced with ``pcdata()`` and ``urlescape()`` with ``urlencode()`` +- the dependencies in the ``Makefile`` must be adapted: replace ``DEPENDS:=gluon-luci-theme`` with ``DEPENDS:=gluon-web-theme``, ``luci-base`` with ``gluon-web`` and ``gluon-luci-admin`` with ``gluon-web-admin`` ... +- ``i18n.translate()`` must be replaced with ``translate()`` +- ``luci.template.render_string()`` must be replaced with ``renderer.render_string()`` +- i.e. ``s:option(cbi.Value, "_altitude" ...`` must be replaced with ``o = s:option(Value, "altitude" ...`` +- ``o.rmempty`` must be replaced with ``o.optional`` +- adapt the paths: ``/lib/gluon/setup-mode/www`` must be replaced with ``/lib/gluon/web/www`` +- includes: ``require 'luci.util'`` must be replaced with ``require 'gluon.web.util'`` and 'luci.i18n', 'gluon.luci' with 'gluon.util' +- In ``site.mk`` all pakages with ``-luci-`` in its name must be replaced with ``-web-`` (exception: ``gluon-luci-portconfig must be replaced with ``gluon-web-network`` +- the Makefile now has to reside in a subfolder within the repository, all files and folders needed for inclusion need to be in that same subfolder +- the ``site.conf`` needs to be adjusted too. Refer to `site.html#configuration18`_ for the +new format: + - The changes in short: the ``fastd_mesh_vpn`` section has been renamed to ``fastd`` + and moved into a new section ``mesh_vpn``, with the exception of the options + ``enabled``, ``mtu`` and ``bandwidth_limit``, which are set directly in the + ``mesh_vpn`` section. + +.. _site.html#configuration18: From c9c389be8f16efd3701da3988be9e4d1c8336dc3 Mon Sep 17 00:00:00 2001 From: rubo77 Date: Thu, 8 Jun 2017 14:19:05 +0200 Subject: [PATCH 3/6] Docs: Make sure all upgrade scripts are executable. --- docs/dev/upgrade.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/dev/upgrade.rst b/docs/dev/upgrade.rst index 64dd59ab..def1da2a 100644 --- a/docs/dev/upgrade.rst +++ b/docs/dev/upgrade.rst @@ -41,3 +41,5 @@ These are some guidelines for the script numbers: * ``5xx``: Miscellaneous (everything not fitting into any other category) * ``6xx`` .. ``8xx``: Currently unused * ``9xx``: Upgrade finalization + +Make sure all upgrade scripts are executable. From 7c11e022c1caecb31ddf56833f71e6d67a42bc8b Mon Sep 17 00:00:00 2001 From: rubo77 Date: Thu, 8 Jun 2017 14:19:23 +0200 Subject: [PATCH 4/6] Docs: Developing Packages --- docs/dev/basics.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst index eecaa142..9b490a9e 100644 --- a/docs/dev/basics.rst +++ b/docs/dev/basics.rst @@ -65,6 +65,35 @@ apply: - use tabs instead of spaces (set your editor to show tabs as two spaces) - trailing whitespaces must be eliminated +Developing Packages +------------------- + +If you want to develop your own external Gluon package, the best way would be +to start with an existing package from the gluon repository and adapt it, for +example use the package ``gluon-web-mesh-vpn-fastd`` as a base + +- rename all occurrences of your example package +- adapt the upgrade script to your needs +- to create new config values that may be editable with ``uci`` create a file + in ``/ect/config/your_new_config`` with just one section + +:: + + config main 'settings' + + +- to fill this section with values from the ``site.conf`` edit the upgrade + script for your package and add the same section as the filename of the config + file in your ``site.conf``: + +:: + + your_new_config { + new_value = 'example' + } + +:: + Upgrading Packages from 2016.2.x -------------------------------- From 2734a486cf3a6fae4c81e5b8681a1bf56d1cad26 Mon Sep 17 00:00:00 2001 From: rubo77 Date: Thu, 8 Jun 2017 18:02:14 +0200 Subject: [PATCH 5/6] Docs: reformated section: Upgrading Packages from 2016.2.x --- docs/dev/basics.rst | 64 +++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst index 9b490a9e..78391742 100644 --- a/docs/dev/basics.rst +++ b/docs/dev/basics.rst @@ -28,7 +28,7 @@ rerun :: - make update + make update `make update` also applies the patches that can be found in the directories found in `patches`; the resulting branch will be called `patched`, while the commit specified in `modules` @@ -40,7 +40,7 @@ using :: - make update-patches + make update-patches If applying a patch fails because you have changed the base commit, the repository will be reset to the old `patched` branch and you can try rebasing it onto the new `base` branch yourself and after that call `make update-patches` to fix the problem. @@ -79,18 +79,18 @@ example use the package ``gluon-web-mesh-vpn-fastd`` as a base :: - config main 'settings' + config main 'settings' - to fill this section with values from the ``site.conf`` edit the upgrade - script for your package and add the same section as the filename of the config - file in your ``site.conf``: + script for your package and add the same section as the filename of the config + file in your ``site.conf``: :: - your_new_config { - new_value = 'example' - } + your_new_config { + new_value = 'example' + } :: @@ -100,25 +100,31 @@ Upgrading Packages from 2016.2.x The site.conf and external packages to be rewritten in some parts and Gluon now doesn't use LuCI for its Config Mode anymore, but our own fork "gluon-web", which is significantly smaller (as lots of features we don't -need have been removed) for detailed changes see `/dev/web/`_. +need have been removed) for detailed changes see section `/web/`_. -.. _/dev/web/: - -- the function ``gluon_luci.escape()`` must be replaced with ``pcdata()`` and ``urlescape()`` with ``urlencode()`` -- the dependencies in the ``Makefile`` must be adapted: replace ``DEPENDS:=gluon-luci-theme`` with ``DEPENDS:=gluon-web-theme``, ``luci-base`` with ``gluon-web`` and ``gluon-luci-admin`` with ``gluon-web-admin`` ... -- ``i18n.translate()`` must be replaced with ``translate()`` -- ``luci.template.render_string()`` must be replaced with ``renderer.render_string()`` -- i.e. ``s:option(cbi.Value, "_altitude" ...`` must be replaced with ``o = s:option(Value, "altitude" ...`` -- ``o.rmempty`` must be replaced with ``o.optional`` -- adapt the paths: ``/lib/gluon/setup-mode/www`` must be replaced with ``/lib/gluon/web/www`` -- includes: ``require 'luci.util'`` must be replaced with ``require 'gluon.web.util'`` and 'luci.i18n', 'gluon.luci' with 'gluon.util' -- In ``site.mk`` all pakages with ``-luci-`` in its name must be replaced with ``-web-`` (exception: ``gluon-luci-portconfig must be replaced with ``gluon-web-network`` -- the Makefile now has to reside in a subfolder within the repository, all files and folders needed for inclusion need to be in that same subfolder -- the ``site.conf`` needs to be adjusted too. Refer to `site.html#configuration18`_ for the -new format: - - The changes in short: the ``fastd_mesh_vpn`` section has been renamed to ``fastd`` - and moved into a new section ``mesh_vpn``, with the exception of the options - ``enabled``, ``mtu`` and ``bandwidth_limit``, which are set directly in the - ``mesh_vpn`` section. - -.. _site.html#configuration18: +- the function ``gluon_luci.escape()`` must be replaced with ``pcdata()`` and + ``urlescape()`` with ``urlencode()`` +- the dependencies in the ``Makefile`` must be adapted: replace + ``DEPENDS:=gluon-luci-theme`` with ``DEPENDS:=gluon-web-theme``, ``luci-base`` + with ``gluon-web`` and ``gluon-luci-admin`` with ``gluon-web-admin`` ... +- ``i18n.translate()`` => ``translate()`` +- ``luci.template.render_string()`` => + ``renderer.render_string()`` +- i.e. ``s:option(cbi.Value, "_altitude" ...`` => + ``o = s:option(Value, "altitude" ...`` +- ``o.rmempty`` => ``o.optional`` +- adapt the paths: ``/lib/gluon/setup-mode/www`` => + ``/lib/gluon/web/www`` +- includes: ``require 'luci.util'`` => ``require 'gluon.web.util'``, 'luci.i18n' and 'gluon.luci' => 'gluon.util' +- ``local uci = luci.model.uci.cursor()`` => ``local uci = require("simple-uci").cursor()`` +- In ``site.mk`` all pakages with ``-luci-`` in its name must be replaced with + ``-web-`` (exception: ``gluon-luci-portconfig`` => + ``gluon-web-network`` +- the Makefile now has to reside in a subfolder within the repository, all + files and folders needed for inclusion need to be in that same subfolder +- the ``site.conf`` needs to be adjusted too. Refer to `site.html#configuration`_ + for the new format: + - The changes in short: the ``fastd_mesh_vpn`` section has been renamed to + ``fastd`` and moved into a new section ``mesh_vpn``, with the exception of + the options ``enabled``, ``mtu`` and ``bandwidth_limit``, which are set + directly in the ``mesh_vpn`` section. From 78e79e1d13955e977ecc5774f7e8324a9f93e4bd Mon Sep 17 00:00:00 2001 From: rubo77 Date: Thu, 8 Jun 2017 20:03:39 +0200 Subject: [PATCH 6/6] Docs: Development Basics - tabs Guidelines hint to Makefile that needs spaces in some places --- docs/dev/basics.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst index 78391742..ce6cf4ac 100644 --- a/docs/dev/basics.rst +++ b/docs/dev/basics.rst @@ -62,7 +62,9 @@ Code formatting may sound like a topic for the pedantic, however it helps if the code in the project is formatted in the same way. The following rules apply: -- use tabs instead of spaces (set your editor to show tabs as two spaces) +- use tabs instead of spaces (set your editor to show tabs as two spaces.) Only + exceptions are Makefiles, that need spaces in some places (for example the + Package definition) - trailing whitespaces must be eliminated Developing Packages