Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • ffbs/ffbs-gluon
  • parabol1337/ffbs-gluon
  • darkbit/ffbs-gluon
3 results
Show changes
Hide whitespace changes
Inline Side-by-side
Showing
with 1356 additions and 571 deletions
contrib/run_qemu.sh 0 → 100755
View file @ e13ecb01
#!/bin/sh
# Note: You can exit the qemu instance by first pressing "CTRL + a" then "c".
# Then you enter the command mode of qemu and can exit by typing "quit".
qemu-system-x86_64 \
-d 'cpu_reset' \
-enable-kvm \
-gdb tcp::1234 \
-nographic \
-netdev user,id=wan,hostfwd=tcp::2223-10.0.2.15:22 \
-device virtio-net-pci,netdev=wan,addr=0x06,id=nic1 \
-netdev user,id=lan,hostfwd=tcp::6080-192.168.1.1:80,hostfwd=tcp::2222-192.168.1.1:22,net=192.168.1.100/24 \
-device virtio-net-pci,netdev=lan,addr=0x05,id=nic2 \
"$@"
contrib/sign.sh
View file @ e13ecb01
#!/bin/sh
if [ $# -eq 0 -o "-h" = "$1" -o "-help" = "$1" -o "--help" = "$1" ]; then
set -e
if [ $# -ne 2 ] || [ "-h" = "$1" ] || [ "--help" = "$1" ] || [ ! -r "$1" ] || [ ! -r "$2" ]; then
cat <<EOHELP
Usage: $0 <secret> <manifest>
......@@ -13,7 +15,7 @@ The script may be performed multiple times to the same document
to indicate an approval by multiple developers.
See also
* edcsautils on https://github.com/tcatm/ecdsautils
* ecdsautils on https://github.com/freifunk-gluon/ecdsautils
EOHELP
exit 1
......@@ -25,16 +27,29 @@ manifest="$2"
upper="$(mktemp)"
lower="$(mktemp)"
awk "BEGIN { sep=0 }
/^---\$/ { sep=1; next }
{ if(sep==0) print > \"$upper\";
else print > \"$lower\"}" \
"$manifest"
trap 'rm -f "$upper" "$lower"' EXIT
ecdsasign "$upper" < "$SECRET" >> "$lower"
awk 'BEGIN {
sep = 0
}
/^---$/ {
sep = 1;
next
}
cat "$upper" > "$manifest"
echo --- >> "$manifest"
cat "$lower" >> "$manifest"
{
if(sep == 0) {
print > "'"$upper"'"
} else {
print > "'"$lower"'"
}
}' "$manifest"
ecdsasign "$upper" < "$SECRET" >> "$lower"
rm -f "$upper" "$lower"
(
cat "$upper"
echo ---
cat "$lower"
) > "$manifest"
contrib/sigtest.sh
View file @ e13ecb01
#!/bin/sh
if [ $# -eq 0 -o "-h" = "$1" -o "-help" = "$1" -o "--help" = "$1" ]; then
cat <<EOHELP
if [ $# -eq 0 ] || [ "-h" = "$1" ] || [ "-help" = "$1" ] || [ "--help" = "$1" ]; then
cat <<EOHELP
Usage: $0 <public> <signed manifest>
sigtest.sh checks if a manifest is signed by the public key <public>. There is
no output, success or failure is indicated via the return code.
See also:
* ecdsautils in https://github.com/tcatm/ecdsautils
* http://gluon.readthedocs.org/en/latest/features/autoupdater.html
* ecdsautils in https://github.com/freifunk-gluon/ecdsautils
* https://gluon.readthedocs.io/en/latest/features/autoupdater.html
EOHELP
exit 1
exit 1
fi
public="$1"
......@@ -21,18 +21,29 @@ upper="$(mktemp)"
lower="$(mktemp)"
ret=1
awk "BEGIN { sep=0 }
/^---\$/ { sep=1; next }
{ if(sep==0) print > \"$upper\";
else print > \"$lower\"}" \
"$manifest"
awk 'BEGIN {
sep = 0
}
while read line
/^---$/ {
sep = 1;
next
}
{
if(sep == 0) {
print > "'"$upper"'"
} else {
print > "'"$lower"'"
}
}' "$manifest"
while read -r line
do
if ecdsaverify -s "$line" -p "$public" "$upper"; then
ret=0
break
fi
if ecdsaverify -s "$line" -p "$public" "$upper"; then
ret=0
break
fi
done < "$lower"
rm -f "$upper" "$lower"
......
docs/Makefile
View file @ e13ecb01
# Makefile for Sphinx documentation
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXOPTS = -W --keep-going
SPHINXBUILD = sphinx-build
PAPER =
SOURCEDIR = .
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
# Put it first so that "make" without argument is like "make help".
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Gluon.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Gluon.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Gluon"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Gluon"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: help Makefile
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
docs/_static/css/custom.css 0 → 100644
View file @ e13ecb01
.strike {
text-decoration: line-through;
}
docs/conf.py
View file @ e13ecb01
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Gluon documentation build configuration file, created by
# sphinx-quickstart on Wed Jan 29 00:45:53 2014.
# Configuration file for the Sphinx documentation builder.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
import sys
import os
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Gluon'
copyright = 'Project Gluon'
author = 'Project Gluon'
# -- General configuration ------------------------------------------------
# The short X.Y version
version = '2023.2.4'
# The full version, including alpha/beta/rc tags
release = version
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.mathjax',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'Gluon'
copyright = '2015, Project Gluon'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '2015.1+'
# The full version, including alpha/beta/rc tags.
release = '2015.1+'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
pygments_style = None
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# Don't highlight code blocks unless requested explicitly
highlight_language = 'none'
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# Ignore links to the config mode, as well as anchors on on hackint, which are
# used to mark channel names and do not exist. Regular links are not effected.
linkcheck_ignore = [
'http://192.168.1.1',
'https://webirc.hackint.org/#'
]
# -- Options for HTML output ----------------------------------------------
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#html_theme = 'default'
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
#
html_static_path = ['_static']
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = ['css/custom.css']
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'Gluondoc'
# -- Options for LaTeX output ---------------------------------------------
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'Gluon.tex', 'Gluon Documentation',
'Project Gluon', 'manual'),
(master_doc, 'Gluon.tex', 'Gluon Documentation',
'Project Gluon', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'gluon', 'Gluon Documentation',
['Project Gluon'], 1)
(master_doc, 'gluon', 'Gluon Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Gluon', 'Gluon Documentation',
'Project Gluon', 'Gluon', 'One line description of project.',
'Miscellaneous'),
(master_doc, 'Gluon', 'Gluon Documentation',
author, 'Gluon', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
docs/dev/basics.rst
View file @ e13ecb01
......@@ -8,17 +8,22 @@ Gluon's source is kept in `git repositories`_ at GitHub.
Bug Tracker
-----------
The `main repo`_ does have issues enabled.
The `main repo`_ does have issues enabled.
.. _main repo: https://github.com/freifunk-gluon/gluon
IRC
---
Gluon's developers frequent `#gluon on hackint`_. You're welcome to join us!
Gluon's developers frequent the IRC chatroom `#gluon`_ on `hackint`_.
There is a `webchat`_ that allows for easy access from within your
web browser. You're welcome to join us!
.. _#gluon on hackint: irc://irc.hackint.org/#gluon
.. _#gluon: ircs://irc.hackint.org/#gluon
.. _hackint: https://hackint.org/
.. _webchat: https://webirc.hackint.org/#irc://irc.hackint.org/#gluon
.. _working-with-repositories:
Working with repositories
-------------------------
......@@ -28,36 +33,53 @@ 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`
can be refered to by the branch `base`.
can be referred to by the branch `base`.
After new patches have been committed on top of the `patched` branch (or existing commits
since the base commit have been edited or removed), the patch directories can be regenerated
using
::
make unpatch
make update-patches
sets the repositories to the `base` branch,
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.
Always call `make update-patches` after making changes to a module repository as `make update` will overwrite your
commits, making `git reflog` the only way to recover them!
::
make patch
make refresh-patches
re-applies the patches by resetting the `patched` branch to `base` and calling `git am`
for the patch files. Calling `make` or a similar command after calling `make unpatch`
is generally not a good idea.
In order to refresh patches when updating feeds or the OpenWrt base, `make refresh-patches` applies and updates all of their patches without installing feed packages to the OpenWrt build system.
After new patches have been commited on top of the patched branch (or existing commits
since the base commit have been edited or removed), the patch directories can be regenerated
using
This command speeds up the maintenance of updating OpenWrt and feeds.
::
Development Guidelines
----------------------
Lua should be used instead of sh whenever sensible. The following criteria
should be considered:
make update-patches
- Is the script doing more than just executing external commands? if so, use Lua
- Is the script parsing/editing json-data? If so, use Lua for speed
- When using sh, use jsonfilter instead of json_* functions for speed
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.
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 basic rules
apply:
Always call `make update-patches` after making changes to a module repository as `make update` will overwrite your
commits, making `git reflog` the only way to recover them!
- use tabs instead of spaces
- trailing whitespace characters must be eliminated
- files need to end with a final newline
- newlines need to have Unix line endings (lf)
To that end we provide a ``.editorconfig`` configuration, which is supported by most
of the editors out there.
If you add Lua scripts to gluon, check formatting with ``luacheck``.
docs/dev/build.rst 0 → 100644
View file @ e13ecb01
Build system
============
This page explains internals of the Gluon build system. It is currently very
incomplete; please contribute if you can!
Feed management
---------------
Rather that relying on the *feed.conf* mechanism of OpenWrt directly, Gluon
manages its feeds (*"modules"*) using a collection of scripts. This solution was
selected for multiple reasons:
- Feeds lists from Gluon base and the site repository are combined
- Patchsets are applied to downloaded feed repositories automatically
The following variables specifically affect the feed management:
GLUON_FEEDS
List of base feeds; defined in file *modules* in Gluon base
GLUON_SITE_FEED
List of site feeds; defined in file *modules* in site config
\*_REPO, \*_BRANCH, \*_COMMIT
Git repository URL, branch and
commit ID of the feeds to use. The branch name may be omitted; the default
branch will be used in this case.
GLUON_BASE_FEEDS
Additional feed definitions to be added to *feeds.conf*
verbatim. By default, this contains a reference to the Gluon base packages;
when using the Gluon build system to build a non-Gluon system, the variable
can be set to the empty string.
Helper scripts
--------------
Several tasks of the build process have been separated from the Makefile into
external scripts, which are stored in the *scripts* directory. This was done to
ease maintenance of these scripts and the Makefile, by avoiding a lot of escaping.
These scripts are either bash or Lua scripts that run on the build system.
default_feeds.sh
Defines the constant ``DEFAULT_FEEDS`` with the names of all feeds listed in
*openwrt/feeds.conf.default*. This script is only used as an include by other
scripts.
feeds.sh
Creates the *openwrt/feeds.conf* file from ``FEEDS`` and ``DEFAULT_FEEDS``. The
feeds from ``FEEDS`` are linked to the matching subfolder of *packages/* and not
explicitly defined feeds of ``DEFAULT_FEEDS`` are setup as dummy (src-dummy).
This *openwrt/feeds.conf* is used to reinstall all packages of all feeds with
the *openwrt/scripts/feeds* tool.
modules.sh
Defines the constants ``GLUON_MODULES`` and ``FEEDS`` by reading the *modules*
files of the Gluon repository root and the site configuration. The returned
variables look like:
- ``FEEDS``: "*feedA feedB ...*"
- ``GLUON_MODULES``: "*openwrt packages/feedA packages/feedB ...*"
This script is only used as an include by other scripts.
patch.sh
(Re-)applies the patches from the *patches* directory to all ``GLUON_MODULES``
and checks out the files to the filesystem.
This is done for each repo by:
- creating a temporary clone of the repo to patch
- only branch *base* is used
- applying all patches via *git am* on top of this temporary *base* branch
- this branch is named *patched*
- copying the temporary clone to the *openwrt* (for OpenWrt Base) or
*packages* (for feeds) folder
- *git fetch* is used with the temporary clone as source
- *git checkout* is called to update the filesystem
- updating all git submodules
This solution with a temporary clone ensures that the timestamps of checked
out files are not changed by any intermediate patch steps, but only when
updating the checkout with the final result. This avoids triggering unnecessary
rebuilds.
update.sh
Sets up a working clone of the ``GLUON_MODULES`` (external repos) from the external
source and installs it into *packages/* directory. It simply tries to set the *base*
branch of the cloned repo to the correct commit. If this fails it fetches the
upstream branch and tries again to set the local *base* branch.
getversion.sh
Used to determine the version numbers of the repositories of Gluon and the
site configuration, to be included in the built firmware images as
*/lib/gluon/gluon-version* and */lib/gluon/site-version*.
By default, this uses ``git describe`` to generate a version number based
on the last git tag. This can be overridden by putting a file called
*.scmversion* into the root of the respective repositories.
A command like ``rm -f .scmversion; echo "$(./scripts/getversion.sh .)" > .scmversion``
can be used before applying local patches to ensure that the reported
version numbers refer to an upstream commit ID rather than an arbitrary
local one after ``git am``.
docs/dev/debugging.rst 0 → 100644
View file @ e13ecb01
Debugging
=========
.. _dev-debugging-kernel-oops:
Kernel Oops
-----------
Sometimes a running Linux kernel detects an error during runtime that can't
be corrected.
This usually generates a stack trace that points to the location in the code
that caused the oops.
Linux kernels in Gluon (and OpenWrt) are stripped.
That means they do not contain any debug symbols.
On one hand this leads to a smaller binary and faster loading times on the
target.
On the other hand this means that in a case of a stack trace the unwinder
can only print memory locations and no further debugging information.
Gluon stores a compressed kernel with debug symbols for every target
in the directory `output/debug/`.
These kernels should be kept along with the images as long as the images
are in use.
This allows the developer to analyse a stack trace later.
Decoding Stacktraces
....................
The tooling is contained in the kernel source tree in the file
`decode_stacktrace.sh <https://github.com/torvalds/linux/blob/master/scripts/decode_stacktrace.sh>`__.
This file and the needed source tree are available in the directory: ::
openwrt/build_dir/target-<architecture>/linux-<architecture>/linux-<version>/
.. note::
Make sure to use a kernel tree that matches the version and patches
that was used to build the kernel.
If in doubt just re-build the images for the target.
Some more information on how to use this tool can be found at
`LWN <https://lwn.net/Articles/592724/>`__.
Obtaining Stacktraces
.....................
On many targets stack traces can be read from the following
location after reboot: ::
/sys/kernel/debug/crashlog
docs/dev/hardware.rst
View file @ e13ecb01
Adding support for new hardware
===============================
Adding hardware support
=======================
This page will give a short overview on how to add support
for new hardware to Gluon.
Hardware requirements
---------------------
Having an ath9k (or ath10k) based WLAN adapter is highly recommended,
Having an ath9k, ath10k or mt76 based WLAN adapter is highly recommended,
although other chipsets may also work. VAP (multiple SSID) support
is a requirement. At the moment, Gluon's scripts can't handle devices
without WLAN adapters (although such environments may also be interesting,
e.g. for automated testing in virtual machines).
with simultaneous AP + Mesh Point (802.11s) operation is required.
.. _hardware-adding-profiles:
Device checklist
----------------
The description of pull requests adding device support must include the
`device integration checklist
<https://github.com/freifunk-gluon/gluon/wiki/Device-Integration-checklist>`_.
The checklist ensures that core functionality of Gluon is well supported on the
device.
Adding profiles
---------------
The vast majority of devices with ath9k WLAN uses the ar71xx target of OpenWrt.
If the hardware you want to add support for is also ar71xx, adding a new profile
is enough.
.. _device-class-definition:
Profiles are defined in ``targets/<target>-<subtarget>/profiles.mk``. There are two macros
used to define which images are generated: ``GluonProfile`` and ``GluonModel``. The following examples
are taken from ``profiles.mk`` of the ``ar71xx-generic`` target::
Device classes
--------------
All supported hardware is categorized into "device classes". This allows to
adjust the feature set of Gluon to the different hardware's capabilities via
``site.mk`` without having to list individual devices.
$(eval $(call GluonProfile,TLWR1043))
$(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v1-squashfs,tp-link-tl-wr1043n-nd-v1))
$(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v2-squashfs,tp-link-tl-wr1043n-nd-v2))
There are currently two devices classes defined: "standard" and "tiny". The
"tiny" class contains all devices that do not meet the following requirements:
The ``GluonProfile`` macro takes at least one parameter, the profile name as it is
defined in the Makefiles of OpenWrt (``openwrt/target/linux/<target>/<subtarget>/profiles/*``
and ``openwrt/target/linux/<target>/image/Makefile``). If the target you are on doesn't define
profiles (e.g. on x86), just add a single profile called ``Generic`` or similar.
- At least 7 MiB of usable firmware space
- At least 64 MiB of RAM (128MiB for devices with ath10k radio)
Target configuration
--------------------
Gluon's hardware support is based on OpenWrt's. For each supported target,
a configuration file exists at ``targets/<target>-<subtarget>`` (or just
``target/<target>`` for targets without subtargets) that contains all
Gluon-specific settings for the target. The generic configuration
``targets/generic`` contains settings that affect all targets.
All targets must be listed in ``target/targets.mk``.
It may optionally take a second parameter which defines additional packages to include for the profile
(e.g. ath10k). The additional packages defined in ``openwrt/target/linux/<target>/<subtarget>/profiles/*``
aren't used.
The target configuration language is based on Lua, so Lua's syntax for variables
and control structures can be used.
The ``GluonModel`` macro takes three parameters: The profile name, the suffix of the image file
generated by OpenWrt (without the file extension), and the final image name of the Gluon image.
The final image name must be the same that is returned by the following command.
::
lua -e 'print(require("platform_info").get_image_name())'
This is just so the autoupdater can work. The command has to be executed _on_ the target (eg. the hardware router with a flashed image). So you'll first have to build an image with a guessed name, and afterwards build a new, correctly named image. On targets which aren't supported by the autoupdater,
``require("platform_info").get_image_name()`` will just return ``nil`` and the final image name
may be defined arbitrarily.
On devices with multiple WLAN adapters, care must also be taken that the primary MAC address is
configured correctly. ``/lib/gluon/core/sysconfig/primary_mac`` should contain the MAC address which
can be found on a label on most hardware; if it does not, ``/lib/gluon/upgrade/core/initial/001-sysconfig``
in ``gluon-core`` might need a fix. (There have also been cases in which the address was incorrect
even on devices with only one WLAN adapter, in these cases an OpenWrt bug was the cause).
Adding support for new hardware targets
---------------------------------------
Adding a new target is much more complex than adding a new profile. There are two basic steps
required for adding a new target:
Adjust packages
'''''''''''''''
One package that definitely needs adjustments for every new target added is ``lua-platform-info``. Just
start with a copy of an existing platform info script, adjust it for the new target, and add the new target
to the list of supported targets in the package Makefile.
On many targets, Gluon's network setup scripts (mainly in the packages ``gluon-core`` and ``gluon-mesh-batman-adv-core``)
won't run correctly without some adjustments, so better double check that everything is fine there (and the files
``primary_mac``, ``lan_ifname`` and ``wan_ifname`` in ``/lib/gluon/core/sysconfig/`` contain sensible values).
Add support to the build system
'''''''''''''''''''''''''''''''
A directory for the new target must be created under ``targets``, and it must be added
to ``targets/targets.mk``. In the new target directory, the following files must be created:
* profiles.mk
* vermagic
* config (optional)
For ``profiles.mk``, see :ref:`hardware-adding-profiles`.
The file ``config`` can be used to add additional, target-specific options to the OpenWrt config.
The files ``vermagic`` must have the correct content so kernel modules from the upstream repositories
can be installed without dependency issues. The OpenWrt version a Gluon release is based on is defined by the upstream package repo URL in ``include/gluon.mk``
(in the variable ``DEFAULT_OPKG_REPO``); at the time this documentation was written, this was ``barrier_breaker/14.07``; whenever
the package repo is updated, all ``vermagic`` files must be updated as well. The command ``make update-vermagic`` can be used to get the correct
vermagic, or update the values when ``DEFAULT_OPKG_REPO`` has changed.
The content is a hash which is part of the version number of the kernel package. So in the case of ``ar71xx-generic`` on
``barrier_breaker``, we look for the kernel package in the directory ``https://downloads.openwrt.org/barrier_breaker/14.07/ar71xx/generic/packages/base/``.
As the kernel package is called ``kernel_3.10.49-1-0114c71ed85677c9c1e4911437af4743_ar71xx.ipk``, the correct ``vermagic`` string
is ``0114c71ed85677c9c1e4911437af4743``.
After this, is should be sufficient to call ``make GLUON_TARGET=<target>`` to build the images for the new target.
Device definitions
~~~~~~~~~~~~~~~~~~
To configure a device to be built for Gluon, the ``device`` function is used.
In the simplest case, only two arguments are passed, for example:
.. code-block:: lua
device('tp-link-tl-wdr3600-v1', 'tplink_tl-wdr3600-v1')
The first argument is the device name in Gluon, which is part of the output
image filename, and must correspond to the model string looked up by the
autoupdater. The second argument is the corresponding device profile name in
OpenWrt, as found in ``openwrt/target/linux/<target>/image/*``.
A table of additional settings can be passed as a third argument:
.. code-block:: lua
device('ubiquiti-edgerouter-x', 'ubnt_edgerouter-x', {
factory = false,
packages = {'-hostapd-mini'},
manifest_aliases = {
'ubnt-erx',
},
})
The supported additional settings are described in the following sections.
Suffixes and extensions
~~~~~~~~~~~~~~~~~~~~~~~
For many targets, OpenWrt generates images with the suffixes
``-squashfs-factory.bin`` and ``-squashfs-sysupgrade.bin``. For devices with
different image names, is it possible to override the suffixes and extensions
using the settings ``factory``, ``factory_ext``, ``sysupgrade`` and
``sysupgrade_ext``, for example:
.. code-block:: lua
{
factory = '-squashfs-combined',
factory_ext = '.img.gz',
sysupgrade = '-squashfs-combined',
sysupgrade_ext = '.img.gz',
}
Only settings that differ from the defaults need to be passed. ``factory`` and
``sysupgrade`` can be set to ``false`` when no such images exist.
For some device types, there are multiple factory images with different
extensions. ``factory_ext`` can be set to a table of strings to account for this
case:
.. code-block:: lua
{
factory_ext = {'.img.gz', '.vmdk', '.vdi'},
}
TODO: Extra images
Aliases and manifest aliases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes multiple devices exist that use the same OpenWrt images. To make it
easier to find these images, the ``aliases`` setting can be used to define
additional device names. Gluon will create symlinks for these names in the
image output directory.
.. code-block:: lua
device('aruba-ap-303', 'aruba_ap-303', {
factory = false,
aliases = {'aruba-instant-on-ap11'},
})
The aliased name will also be added to the autoupdater manifest, allowing upgrade
images to be found under the different name on targets that perform model name
detection at runtime.
It is also possible to add alternative names to the autoupdater manifest without
creating a symlink by using ``manifest_aliases`` instead of ``aliases``, which
should be done when the alternative name does not refer to a separate device.
This is particularly useful to allow the autoupdater to work when the model name
changed between Gluon versions.
Package lists
~~~~~~~~~~~~~
Gluon generates lists of packages that are installed in all images based on a
default list and the features and packages specified in the site configuration.
In addition, OpenWrt defines additional per-device package lists. These lists
may be modified in Gluon's device definitions, for example to include additional
drivers and firmware, or to remove unneeded software. Packages to remove are
prefixed with a ``-`` character.
For many ath10k-based devices, this is used to replace the "CT" variant of
ath10k with the mainline-based version:
.. code-block:: lua
local ATH10K_PACKAGES_QCA9880 = {
'kmod-ath10k',
'-kmod-ath10k-ct',
'-kmod-ath10k-ct-smallbuffers',
'ath10k-firmware-qca988x',
'-ath10k-firmware-qca988x-ct',
}
device('openmesh-a40', 'openmesh_a40', {
packages = ATH10K_PACKAGES_QCA9880,
factory = false,
})
This example also shows how to define a local variable, allowing the package
list to be reused for multiple devices.
Device flags
~~~~~~~~~~~~
The settings ``class``, ``deprecated`` or ``broken`` should be set according to
the device support status. The default values are as follows:
.. code-block:: lua
{
class = 'standard',
deprecated = false,
broken = false,
}
- Device classes are described in :ref:`device-class-definition`
- Broken devices are untested or do not meet our requirements as given by the
device checklist
- Deprecated devices are slated for removal in a future Gluon version due to
hardware constraints
Global settings
~~~~~~~~~~~~~~~
There is a number of directives that can be used outside of a ``device()``
definition:
- ``include('filename')``: Include another file with global settings
- ``config(key, value)``: Set a config symbol in OpenWrt's ``.config``. Value
may be a string, number, boolean, or nil. Booleans and nil are used for
tristate symbols, where nil sets the symbol to ``m``.
- ``try_config(key, value)``: Like ``config()``, but do not fail if setting
the symbol is not possible (usually because its dependencies are not met)
- ``packages { 'package1', '-package2', ... }``: Define a list of packages to
add or remove for all devices of a target. Package lists passed to multiple
calls of ``packages`` will be aggregated.
- ``defaults { key = value, ... }``: Set default values for any of the
additional settings that can be passed to ``device()``.
Helper functions
~~~~~~~~~~~~~~~~
The following helpers can be used in the target configuration:
- ``env.KEY`` allows to access environment variables
- ``istrue(value)`` returns true if the passed string is a positive number
(often used with ``env``, for example ``if istrue(env.GLUON_DEBUG) then ...``)
Hardware support in packages
----------------------------
In addition to the target configuration files, some device-specific changes may
be required in packages.
gluon-core
~~~~~~~~~~
- ``/lib/gluon/upgrade/010-primary-mac``: Override primary MAC address selection
Usually, the primary (label) MAC address is defined in OpenWrt's Device Trees.
For devices or targets where this is not the case, it is possible to specify
what interface to take the primary MAC address from in ``010-primary-mac``.
- ``/lib/gluon/upgrade/020-interfaces``: Override LAN/WAN interface assignment
On PoE-powered devices, the PoE input port should be "WAN".
- ``/usr/lib/lua/gluon/platform.lua``: Contains a list of outdoor devices
gluon-setup-mode
~~~~~~~~~~~~~~~~
- ``/lib/gluon/upgrade/320-setup-ifname``: Contains a list of devices that use
the WAN port for the config mode
On PoE-powered devices, the PoE input port should be used for the config
mode. This is handled correctly by default for outdoor devices listed in
``platform.lua``.
libplatforminfo
~~~~~~~~~~~~~~~
When adding support for a new target to Gluon, it may be necessary to adjust
libplatforminfo to define how autoupdater image names are derived from the
model name.
docs/dev/i18n.rst deleted 100644 → 0
View file @ 2fefdeee
Internationalization support
============================
General guidelines
------------------
* All config mode packages must be fully translatable, with complete English and German texts.
* All new expert mode packages be fully translatable. English texts are required, German texts recommended.
* Existing expert mode packages should be made translatable as soon as possible.
* The "message IDs" (which are the arguments to the ``translate`` function) should be the
English texts.
i18n support in LuCI
--------------------
Internationalization support can be found in the ``luci.i18n`` package.
Strings are translated using the ``i18n.translate`` and ``i18n.translatef`` functions
(``translate`` for static strings, ``translatef`` for printf-like formatted string).
Example from the ``gluon-config-mode-geo-location`` package::
local i18n = require "luci.i18n"
o = s:option(cbi.Flag, "_location", i18n.translate("Show node on the map"))
Adding translation templates to Gluon packages
----------------------------------------------
The i18n support is based on the standard gettext system. For each translatable package,
a translation template with extension ``.pot`` can be created using the ``i18n-scan.pl``
script from the LuCI repository::
cd package/gluon-config-mode-geo-location
mkdir i18n
cd i18n
../../../packages/luci/build/i18n-scan.pl ../files > gluon-config-mode-geo-location.pot
The entries in the template can be reordered after the generation if desirable. Lots of standard
translations like "Cancel" are already available in the LuCI base translation file (see
``packages/luci/po/templates/base.pot``) and can be removed from the template.
In addition, some additions to the Makefile must be made. Instead of OpenWrt's default package.mk,
the Gluon version ``$(GLUONDIR)/include/package.mk`` must be used. The i18n files must be installed
and PKG_CONFIG_DEPENDS must be added::
...
include $(GLUONDIR)/include/package.mk
PKG_CONFIG_DEPENDS += $(GLUON_I18N_CONFIG)
...
define Build/Compile
$(call GluonBuildI18N,gluon-config-mode-geo-location,i18n)
endef
define Package/gluon-config-mode-geo-location/install
...
$(call GluonInstallI18N,gluon-config-mode-geo-location,$(1))
endef
...
Adding translations
-------------------
A new translation file for a template can be added using the ``msginit`` command::
cd package/gluon-config-mode-geo-location/i18n
msginit -l de
This will create the file ``de.po`` in which the translations can be added.
The translation file can be updated to a new template version using the ``msgmerge`` command::
msgmerge -U de.po gluon-config-mode-geo-location.pot
After the merge, the translation file should be checked for "fuzzy matched" entries where
the original English texts have changed. All entries from the the translation file should be
translated in the ``.po`` file (or removed from it, so the original English texts are displayed
instead).
Adding support for new languages
--------------------------------
A list of all languages supported by LuCI can be found in the ``packages/luci/luci.mk`` file after
Gluon's dependencies have been downloaded using ``make update``. Adding translations for these
languages is straightforward using the ``msginit`` command.
For other languages, support must be added tu LuCI first, which constitutes completely translating
the ``base.pot``. Please contact the upstream LuCI maintainers if you'd like to do this.
docs/dev/mac_addresses.rst 0 → 100644
View file @ e13ecb01
MAC addresses
=============
Many devices don't have enough unique MAC addresses assigned by the vendor
(in batman-adv, each mesh interface needs an own MAC address that must be unique
mesh-wide).
Gluon tries to solve this issue by using a hash of the primary MAC address as a
45 bit MAC address prefix. The resulting 8 addresses are used as follows:
* 0: client0; WAN
* 1: mesh0
* 2: owe0
* 3: wan_radio0 (private WLAN); batman-adv primary address
* 4: client1; LAN
* 5: mesh1
* 6: owe1
* 7: wan_radio1 (private WLAN); mesh VPN
docs/dev/packages.rst 0 → 100644
View file @ e13ecb01
Package development
###################
Gluon packages are OpenWrt packages and follow the same rules described at https://openwrt.org/docs/guide-developer/packages.
Development workflow
====================
When you are developing packages, it often happens that you iteratively want to deploy
and verify the state your development. There are two ways to verify your changes:
1)
One way is to rebuild the complete firmware, flash it, configure it and verify your
development then. This usually takes at least a few minutes to get your changes
working so you can test them. Especially if you iterate a lot, this becomes tedious.
2)
Another way is to rebuild only the package you are currently working on and
to deploy this package to your test system. Here not even a reboot is required.
This makes iterating relatively fast. Your test system could be real hardware or
even a qemu in most cases.
Gluon provides scripts to enhance workflow 2). Here is an example illustrating
the workflow using these scripts:
.. code-block:: shell
# start a local qemu instance
contrib/run_qemu.sh output/images/factory/[...]-x86-64.img
# apply changes to the desired package
vi package/gluon-ebtables/files/etc/init.d/gluon-ebtables
# rebuild and push the package to the qemu instance
contrib/push_pkg.sh package/gluon-ebtables/
# test your changes
...
# do more changes
...
# rebuild and push the package to the qemu instance
contrib/push_pkg.sh package/gluon-ebtables/
# test your changes
...
(and so on...)
# see help of the script for more information
contrib/push_pkg.sh -h
...
Features of ``push_pkg.sh``:
* Works with compiled and non-compiled packages.
* This means it can be used in the development of C-code, Lua-Code and mostly any other code.
* Works with native OpenWrt and Gluon packages.
* Pushes to remote machines or local qemu instances.
* Pushes multiple packages in one call if desired.
* Performs site.conf checks.
Implementation details of ``push_pkg.sh``:
* First, the script builds an opkg package using the OpenWrt build system.
* This package is pushed to a *target machine* using scp:
* By default the *target machine* is a locally running x86 qemu started using ``run_qemu.sh``.
* The *target machine* can also be remote machine. (See the cli switch ``-r``)
* Remote machines are not limited to a specific architecture. All architectures supported by gluon can be used as remote machines.
* Finally opkg is used to install/update the packages in the target machine.
* While doing this, it will not override ``/etc/config`` with package defaults by default. (See the cli switch ``-P``).
* While doing this, opkg calls the ``check_site.lua`` from the package as post_install script to validate the ``site.conf``. This means that the ``site.conf`` of the target machine is used for this validation.
Note that:
* ``push_pkg.sh`` does neither build nor push dependencies of the packages automatically. If you want to update dependencies, you must explicitly specify them to be pushed.
* If you add new packages, you must run ``make update config GLUON_TARGET=...``.
* You can change the gluon target of the target machine via ``make config GLUON_TARGET=...``.
* If you want to update the ``site.conf`` of the target machine, use ``push_pkg.sh package/gluon-site/``.
* Sometimes when things break, you can heal them by compiling a package with its dependencies: ``cd openwrt; make package/gluon-ebtables/clean; make package/gluon-ebtables/compile; cd ..``.
* You can exit qemu by pressing ``CTRL + a`` and ``c`` afterwards.
Gluon package makefiles
=======================
As many packages share the same or a similar structure, Gluon provides a ``package/gluon.mk`` that
can be included for common definitions. This file replaces OpenWrt's ``$(INCLUDE_DIR)/package.mk``;
it is usually included as ``include ../gluon.mk`` from Gluon core packages, or as
``include $(TOPDIR)/../package/gluon.mk`` from feeds.
Provided macros
***************
* *GluonBuildI18N* (arguments: *<source directory>*)
Converts the *.po* files for all enabled languages from the given source directory to
the binary *.lmo* format and stores them in ``$(PKG_BUILD_DIR)/i18n``.
* *GluonInstallI18N*
Install *.lmo* files from ``$(PKG_BUILD_DIR)/i18n`` to ``/lib/gluon/web/i18n`` in the
package install directory.
* *GluonSrcDiet* (arguments: *<source directory>*, *<destination directory>*)
Copies a directory tree, processing all files in it using *LuaSrcDiet*. The directory
tree should only contain Lua files.
* *GluonCheckSite* (arguments: *<source file>*)
Intended to be used in a package postinst script. It will use the passed Lua
snippet to verify package-specific site configuration.
* *BuildPackageGluon* (replaces *BuildPackage*)
Extends the *Package/<name>* definition with common defaults, sets the package
install script to the common *Gluon/Build/Install*, and automatically creates
a postinst script using *GluonCheckSite* if a ``check_site.lua`` is found in the
package directory.
Default build steps
*******************
These defaults greatly reduce the boilerplate in each package, but they can also
be confusing because of the many implicit behaviors depending on files in the
package directory. If any part of *Gluon/Build/Compile* or *Gluon/Build/Install*
does not work as intended for a package, the compile and install steps can
always be replaced or extended.
*Build/Compile* is set to *Gluon/Build/Compile* by default, which will
* run OpenWrt standard default commands (*Build/Compile/Default*) if a ``src/Makefile``
or ``src/CMakeLists.txt`` is found
* run *GluonSrcDiet* on all files in the ``luasrc`` directory
* run *GluonBuildI18N* if a ``i18n`` directory is found
*Package/<name>* defaults to *Gluon/Build/Install* for packages defined using
*BuildPackageGluon*, which will
* copy all files from ``$(PKG_INSTALL_DIR)`` into the package if ``$(PKG_INSTALL)`` is 1
* copy all files from ``files`` into the package
* copy all Lua files built from ``luasrc`` into the package
* installs ``$(PKG_BUILD_DIR)/respondd.so`` to ``/usr/lib/respondd/$(PKG_NAME).so`` if ``src/respondd.c`` exists
* installs compiled i18n *.lmo* files
Feature flags
=============
Feature flags provide a convenient way to define package selections without
making it necessary to list each package explicitly. The list of features to
enable for a Gluon build is determined by the evaluated image-customization.lua file
in the root-directory of the Site repository.
The main feature flag definition file is ``package/features``, but each package
feed can provide additional definitions in a file called ``features`` at the root
of the feed repository.
Each flag *$flag* will include the package the name *gluon-$flag* by default.
The feature definition file can modify the package selection by adding or removing
packages when certain combinations of flags are set.
Feature definitions use Lua syntax. Two basic functions are defined:
* *feature(name, pkgs)*: Defines a new feature. *feature()* expects a feature
(flag) name and a list of packages to add or remove when the feature is
enabled.
* Defining a feature using *feature* replaces the default definition of
just including *gluon-$flag*.
* A package is removed when the package name is prefixed with a ``-`` (after
the opening quotation mark).
* *when(expr, pkgs)*: Adds or removes packages when a given logical expression
of feature flags is satisfied.
* *expr* is a logical expression composed of feature flag names (each prefixed
with an underscore before the opening quotation mark), logical operators
(*and*, *or*, *not*) and parentheses.
* Referencing a feature flag in *expr* has no effect on the default handling
of the flag. When no *feature()* entry for a flag exists, it will still
add *gluon-$flag* by default.
* *pkgs* is handled as for *feature()*.
Example::
feature('web-wizard', {
'gluon-config-mode-hostname',
'gluon-config-mode-geo-location',
'gluon-config-mode-contact-info',
'gluon-config-mode-outdoor',
})
when(_'web-wizard' and (_'mesh-vpn-fastd' or _'mesh-vpn-tunneldigger'), {
'gluon-config-mode-mesh-vpn',
})
feature('no-radvd', {
'-gluon-radvd',
})
This will
* disable the inclusion of the (non-existent) packages *gluon-web-wizard* and *gluon-no-radvd* when their
corresponding feature flags are evaluated as selected in the image-customization.lua file
* enable four additional config mode packages when the *web-wizard* feature is enabled
* enable *gluon-config-mode-mesh-vpn* when both *web-wizard* and one
of *mesh-vpn-fastd* and *mesh-vpn-tunneldigger* are enabled
* disable the *gluon-radvd* package when *gluon-no-radvd* is enabled
docs/dev/site_library.rst 0 → 100644
View file @ e13ecb01
gluon.site library
==================
The *gluon.site* library allows convenient access to the site configuration
from Lua scripts. Example:
.. code-block:: lua
local site = require 'gluon.site'
print(site.wifi24.ap.ssid())
The *site* object in this example does not directly represent the *site.conf* data structure;
instead, it is wrapped in a way that makes it more convenient to access deeply nested elements.
To access the underlying values, they must be unwrapped using the function call notation
(the ``()`` after ``site.wifi24.ap.ssid`` in the example).
The wrapper objects have two advantages over simple Lua tables:
* Accessing non-existing values is never an error: ``site.wifi24.ap.ssid()`` will simply
return *nil* if ``site.wifi24`` or ``site.wifi24.ap`` do not exist
* Default values: A default value can be passed to the unwrapping function call:
.. code-block:: lua
print(site.wifi24.ap.ssid('Default'))
will return *'Default'* instead of *nil* when the value is unset.
Note that *nil* values and unset values are equivalent in Lua.
A simple way to access the whole site configuration as a simple table
is to unwrap the top-level site object:
.. code-block:: lua
local site_table = site()
docs/dev/upgrade.rst
View file @ e13ecb01
......@@ -6,7 +6,7 @@ Basics
After each sysupgrade (including the initial installation), Gluon will execute all scripts
under ``/lib/gluon/upgrade``. These scripts' filenames usually begin with a 3-digit number
specifying the order of execution.
specifying the order of execution. Note that the script files need to be executable.
To get an overview of the ordering of all scripts of all packages, the helper script ``contrib/lsupgrade.sh``
in the Gluon repository can be used, which will print all upgrade scripts' filenames and directories. If executed
......@@ -16,17 +16,15 @@ Best practices
--------------
* Most upgrade scripts are written in Lua. This allows using lots of helper functions provided
by LuCi and Gluon, e.g. to access the site configuration or edit UCI configuration files.
by Gluon, e.g. to access the site configuration or edit UCI configuration files.
* Whenever possible, scripts shouldn't check if they are running for the first time, but just edit configuration
files to achive a valid configuration (without overwriting configuration changes made by the user where desirable).
files to achieve a valid configuration (without overwriting configuration changes made by the user where desirable).
This allows using the same code to create the initial configuration and upgrade configurations on upgrades.
* If it is unavoidable to run different code during the initial installation, the ``sysconfig.gluon_version`` variable
can be checked. This variable in ``nil`` during the initial installation and contains the previously install Gluon
version otherwise. The package ``gluon-legacy`` (which is responsible for upgrades from the old firmwares of
Hamburg/Kiel/Lübeck) uses the special value ``legacy``; other packages should handle this value just as any other
string.
can be checked. This variable is ``nil`` during the initial installation and contains the previously installed Gluon
version otherwise.
Script ordering
---------------
......
docs/dev/wan.rst → docs/dev/uplink.rst
View file @ e13ecb01
WAN support
===========
Uplink support
==============
As the WAN port of a node will be connected to a user's private network, it
is essential that the node only uses the WAN when it is absolutely necessary.
There are two cases in which the WAN port is used:
* Mesh VPN (package ``gluon-mesh-vpn-fastd``
* Mesh VPN (package ``gluon-mesh-vpn-fastd``)
* DNS to resolve the VPN servers' addresses (package ``gluon-wan-dnsmasq``)
After the VPN connection has been established, the node should be able to reach
the mesh's DNS servers and use these for all other name resolution.
If a device has only a single Ethernet port (or group of ports), it will be
used as an uplink port even when it is not labelled as "WAN" by default. This
behavior can be controlled using the ``interfaces.single.default_roles``
site.conf option. It is also possible to alter the interface assignment after
installation by modifying ``/etc/config/gluon`` and running
``gluon-reconfigure``.
Routing tables
~~~~~~~~~~~~~~
......@@ -46,4 +52,4 @@ so the WAN DNS servers aren't leaked to the primary DNS daemon.
*libpacketmark* is used to make the secondary DNS daemon send its requests over the WAN interface.
The package ``gluon-mesh-vpn-fastd`` provides an iptables rule which will redirect all DNS requests from processes running
with the primary group ``gluon-fastd`` to ``127.0.0.1:54``, thus making fastd use the secondary DNS daemon.
with the primary group ``gluon-mesh-vpn`` to ``127.0.0.1:54``, thus making fastd use the secondary DNS daemon.
docs/dev/configmode.rst → docs/dev/web/config-mode.rst
View file @ e13ecb01
Config Mode
===========
As of 2014.4 `gluon-config-mode` consists of several modules.
The `Config Mode` consists of several modules that provide a range of different
configuration options:
gluon-config-mode-core
This modules provides the core functionality for the config mode.
......@@ -22,20 +23,13 @@ gluon-config-mode-geo-location
gluon-config-mode-contact-info
Adds a field where the user can provide contact information.
In order to get a config mode close to the one found in 2014.3.x you may add
these modules to your `site.mk`:
gluon-config-mode-hostname,
gluon-config-mode-autoupdater,
gluon-config-mode-mesh-vpn,
gluon-config-mode-geo-location,
gluon-config-mode-contact-info
Writing Config Mode Modules
Writing Config Mode modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Config mode modules are located at `/lib/gluon/config-mode/wizard` and
`/lib/gluon/config-mode/reboot`. Modules are named like `0000-name.lua` and
are executed in lexical order. If you take the standard set of modules, the
Config mode modules are located at ``/lib/gluon/config-mode/wizard`` and
``/lib/gluon/config-mode/reboot``. Modules are named like ``0000-name.lua`` and
are executed in lexical order. In the standard package set, the
order is, for wizard modules:
- 0050-autoupdater-info
......@@ -44,49 +38,45 @@ order is, for wizard modules:
- 0400-geo-location
- 0500-contact-info
While for reboot modules it is:
The reboot module order is:
- 0100-mesh-vpn
- 0900-msg-reboot
All modules are run in the gluon-web model context and have access to the same
variables as "full" gluon-web modules.
Wizards
-------
Wizard modules return a UCI section. A simple module capable of changing the
hostname might look like this::
Wizard modules must return a function that is provided with the wizard form and an
UCI cursor. The function can create configuration sections in the form:
local cbi = require "luci.cbi"
local uci = luci.model.uci.cursor()
.. code-block:: lua
local M = {}
function M.section(form)
local s = form:section(cbi.SimpleSection, nil, nil)
local o = s:option(cbi.Value, "_hostname", "Hostname")
o.value = uci:get_first("system", "system", "hostname")
o.rmempty = false
return function(form, uci)
local s = form:section(Section)
local o = s:option(Value, "hostname", "Hostname")
o.default = uci:get_first("system", "system", "hostname")
o.datatype = "hostname"
end
function M.handle(data)
uci:set("system", uci:get_first("system", "system"), "hostname", data._hostname)
uci:save("system")
uci:commit("system")
function o:write(data)
uci:set("system", uci:get_first("system", "system"), "hostname", data)
end
return {'system'}
end
return M
The function may return a table of UCI packages to commit after the individual
fields' `write` methods have been executed. This is done to avoid committing the
packages repeatedly when multiple wizard modules modify the same package.
Reboot page
-----------
Reboot modules return a function that will be called when the page is to be
rendered or nil (i.e. the module is skipped)::
Reboot modules are simply executed when the reboot page is
rendered:
if no_hello_world_today then
return nil
else
return function ()
luci.template.render_string("Hello World!")
end
end
.. code-block:: lua
renderer.render_string("Hello World!")
docs/dev/web/controller.rst 0 → 100644
View file @ e13ecb01
Controllers
===========
Controllers live in the ``controller`` subdirectory of a gluon-web application
(``/lib/gluon/config-mode/controller`` for the config mode,
``/lib/gluon/status-page/controller`` for the status page). They define which pages ("routes")
exist under the application base URL, and what code is run when these pages are requested.
Controller scripts usually start with a *package* declaration, followed by calls
to the *entry* function, which each define one route:
.. code-block:: lua
package 'gluon-web-admin'
entry({"admin"}, alias("admin", "info"), _("Advanced settings"), 10)
entry({"admin", "info"}, template("admin/info"), _("Information"), 1)
*package* defines the translation namespace for the titles of the defined
pages as well as the referenced views and models. The entry function expects 4
arguments:
- `path`: Components of the path to define a route for.
The above example defines routes for the paths ``admin`` and ``admin/info``.
- `target`: Dispatcher for the route. See the following section for details.
- `title`: Page title (also used in navigation). The underscore function is used
to mark the strings as translatable for ``i18n-scan.pl``.
- `order`: Sort index in navigation (defaults to 100)
Navigation indexes are automatically generated for each path level. Pages can be
hidden from the navigation by setting the `hidden` property of the node object
returned by `entry`:
.. code-block:: lua
entry({"hidden"}, alias("foo"), _("I'm hidden!")).hidden = true
Dispatchers
-----------
- *alias* (*path*, ...): Redirects to a different page. The path components are
passed as individual arguments.
- *call* (*func*, ...): Runs a Lua function for custom request handling. The given
function is called with the HTTP object and the template renderer as first
two arguments, followed by all additional arguments passed to `call`.
- *template* (*view*): Renders the given view. See :doc:`view`.
- *model* (*name*): Displays and evaluates a form as defined by the given model. See the
:doc:`model` page for an explanation of gluon-web models.
.. _web-controller-http:
The HTTP object
---------------
The HTTP object provides information about the HTTP requests and allows to add
data to the reply. Using it directly is rarely necessary when gluon-web
models and views are used.
Useful functions:
- *getenv* (*key*): Returns a value from the CGI environment passed by the webserver.
- *formvalue* (*key*): Returns a value passed in a query string or in the content
of a POST request. If multiple values with the same name have been passed, only
the first is returned.
- *formvaluetable* (*key*): Similar to *formvalue*, but returns a table of all
values for the given key.
- *status* (*code*, *message*): Writes the HTTP status to the reply. Has no effect
if a status has already been sent or non-header data has been written.
- *header* (*key*, *value*): Adds an HTTP header to the reply to be sent to
the client. Has no effect when non-header data has already been written.
- *prepare_content* (*mime*): Sets the *Content-Type* header to the given MIME
type
- *write* (*data*, ...): Sends the given data to the client. If headers have not
been sent, it will be done before the data is written.
HTTP functions are called in method syntax, for example:
.. code-block:: lua
http:write('Output!')
.. _web-controller-template-renderer:
The template renderer
---------------------
The template renderer allows to render templates (views). The most useful functions
are:
- *render* (*view*, *scope*, *pkg*): Renders the given view, optionally passing a table
with additional variables to make available in the template. The passed package
defines the translation namespace.
- *render_string* (*str*, *scope*, *pkg*): Same as *render*, but the template is passed
directly instead of being loaded from the view directory.
The renderer functions are called in property syntax, for example:
.. code-block:: lua
renderer.render('layout')
Differences from LuCI
---------------------
- Controllers must not use the *module* function to define a Lua module (*gluon-web*
will set up a proper environment for each controller itself)
- Entries are defined at top level, not inside an *index* function
- The *alias* dispatcher triggers an HTTP redirect instead of directly running
the dispatcher of the aliased route.
- The *call* dispatcher is passed a function instead of a string with a function
name.
- The *cbi* dispatcher of LuCI has been renamed to *model*.
- The HTTP POST handler support the multipart/form-data encoding only, so
``enctype="multipart/form-data"`` must be included in all *<form>* HTML
elements.
- Other dispatchers like *form* are not provided.
docs/dev/web/i18n.rst 0 → 100644
View file @ e13ecb01
Internationalization support
============================
General guidelines
------------------
* All config mode packages must be fully translatable, with complete English and German texts.
* All new expert mode packages must be fully translatable. English texts are required.
* German translations are recommended. Other supported languages, especially French, are
nice-to-have, but not required. If you don't know a language well, rather leave the translation
blank, so it is obvious that there is no proper translation yet.
* Existing expert mode packages should be made translatable as soon as possible.
* The "message IDs" (which are the arguments to the *translate* function) should be the
English texts.
i18n support in Gluon
---------------------
Internationalization support is available in all components (models, view and
controllers) of *gluon-web*-based packages. Strings are translated using the *translate*,
*_translate* and *translatef* functions (*translate* for static strings, *translatef*
for printf-like formatted string; *_translate* works the same as *translate*, but
will return *nil* instead of the original string when no translation is available).
In views, the special tags ``<%:...%>`` can be used to translate the contained string.
Example from the *gluon-config-mode-geo-location* package:
.. code-block:: lua
local share_location = s:option(Flag, "location", translate("Show node on the map"))
Note that translations are *namespaced*: each package will only use its own
translation strings by default. For this purpose, the package name must by
specified in a package's controller. It is possible to access a different
translation package using the *i18n* function from models and view, which is
necessary when strings from the site configuration are used, or packages do not
have their own controller (which is the case for config mode wizard components).
.. code-block:: lua
local site_i18n = i18n 'gluon-site'
local msg = site_i18n._translate('gluon-config-mode:welcome')
Adding translation templates to Gluon packages
----------------------------------------------
The i18n support is based on the standard gettext system. For each translatable package,
a translation template with extension ``.pot`` can be created using the *i18n-scan.pl*
script in the ``contrib`` directory:
.. code-block:: sh
cd package/gluon-web-mesh-vpn-fastd
mkdir i18n
cd i18n
../../../contrib/i18n-scan.pl ../files ../luasrc > gluon-web-mesh-vpn-fastd.pot
The same command can be run again to update the template.
In addition, the Makefile must be adjusted. Instead of OpenWrt's default *package.mk*,
the Gluon version (``../gluon.mk`` for core packages) must be used. The i18n files must be installed
and PKG_CONFIG_DEPENDS must be added::
...
include ../gluon.mk
PKG_CONFIG_DEPENDS += $(GLUON_I18N_CONFIG)
...
define Build/Compile
$(call GluonBuildI18N,gluon-web-mesh-vpn-fastd,i18n)
endef
define Package/gluon-web-mesh-vpn-fastd/install
...
$(call GluonInstallI18N,gluon-web-mesh-vpn-fastd,$(1))
endef
...
Adding translations
-------------------
A new translation file for a template can be added using the *msginit* command:
.. code-block:: sh
cd package/gluon-web-mesh-vpn-fastd/i18n
msginit -l de
This will create the file *de.po* in which the translations can be added.
The translation file can be updated to a new template version using the *msgmerge* command:
.. code-block:: sh
msgmerge -U de.po gluon-web-mesh-vpn-fastd.pot
After the merge, the translation file should be checked for "fuzzy matched" entries where
the original English texts have changed. All entries from the translation file should be
translated in the *.po* file (or removed from it, so the original English texts are displayed
instead).
Adding support for new languages
--------------------------------
A list of all languages supported by *gluon-web* can be found in ``package/gluon.mk``.
New languages just need to be added to *GLUON_SUPPORTED_LANGS*, and a human-readable
language name must be defined.
docs/dev/web/model.rst 0 → 100644
View file @ e13ecb01
Models
======
Models are defined in the ``model`` subdirectory of a gluon-web application
(``/lib/gluon/config-mode/model`` for the config mode; the status
page does not use any models). Model support is not part of the gluon-web core
anymore, but is provided by the *gluon-web-model* package.
Each model defines one or more forms to display on a page, and how the submitted
form data is handled.
Let's start with an example:
.. code-block:: lua
local f = Form(translate('Hostname'))
local s = f:section(Section)
local o = s:option(Value, 'hostname', translate('Hostname'))
o.default = uci:get_first('system', 'system', 'hostname')
function o:write(data)
uci:set('system', uci:get_first('system', 'system'), 'hostname', data)
uci:commit('system')
end
return f
The top-level element of a model is always a *Form*, but it is also possible for
a model to return multiple forms, which are displayed one below the other.
A *Form* has one or more *Sections*, and each *Section* has different types
of options.
All of these elements have an *id*, which is used to identify them in the HTML
form and handlers. If no ID is given, numerical IDs will be assigned automatically,
but using explicitly named elements is often advisable (and it is required if a
form does not always include the same elements, i.e., some forms, sections or
options are added conditionally). IDs are hierarchical, so in the above example,
the *Value* would get the ID ``1.1.hostname`` (value *hostname* in first section
of first form).
Classes and methods
-------------------
- *Form* (*title*, *description*, *id*)
- *Form:section* (*type*, *title*, *description*, *id*)
Creates a new section of the given type (usually *Section*).
- *Form:write* ()
Is called after the form has been submitted (but only if the data is valid). It
is called last (after all options' *write* methods) and is usually used
to commit changed UCI packages.
The default implementation of *write* doesn't do anything, but it can be
overridden.
- *Section* (usually instantiated through *Form:section*)
- *Section:option* (*type*, *id*, *title*, *description*)
Creates a new option of the given type. Option types:
- *Value*: simple text entry
- *TextValue*: multiline text field
- *ListValue*: radio buttons or dropdown selection
- *DynamicList*: variable number of text entry fields
- *Flag*: checkbox
Most option types share the same properties and methods:
- *default*: default value
- *optional*: value may be empty
- *datatype*: one of the types described in :ref:`web-model-datatypes`
By default (when *datatype* is *nil*), all values are accepted.
- *state*: has one of the values *FORM_NODATA*, *FORM_VALID* and *FORM_INVALID*
when read in a form handler
An option that has not been submitted because of its dependencies will have
the state *FORM_NODATA*, *FORM_INVALID* if the submitted value is not valid
according to the set *datatype*, and *FORM_VALID* otherwise.
- *data*: can be read in form handlers to get the submitted value
- *depends* (*self*, *option*, *value*): adds a dependency on another option
The option will only be shown when the passed option has the given value. This
is mainly useful when the other value is a *Flag* or *ListValue*.
- *depends* (*self*, *deps*): adds a dependency on multiple other options
*deps* must be a table with options as keys and values as values. The option
will only be shown when all passed options have the corresponding values.
Multiple alternative dependencies can be added by calling *depends* repeatedly.
- *value* (*self*, *value*, *text*): adds a choice to a *ListValue*
- *write* (*self*, *data*): is called with the submitted value when all form data is valid.
Does not do anything by default, but can be overridden.
The *default* value, the *value* argument to *depends* and the output *data* always have
the same type, which is usually a string (or *nil* for optional values). Exceptions
are:
- *Flag* uses boolean values
- *DynamicList* uses a table of strings
Despite its name, the *datatype* setting does not affect the returned value type,
but only defines a validator the check the submitted value with.
For a more complete example that actually makes use of most of these features,
have a look at the model of the *gluon-web-network* package.
.. _web-model-datatypes:
Data types
----------
- *integer*: an integral number
- *uinteger*: an integral number greater than or equal to zero
- *float*: a number
- *ufloat*: a number greater than or equal to zero
- *ipaddr*: an IPv4 or IPv6 address
- *ip4addr*: an IPv4 address
- *ip6addr*: an IPv6 address
- *wpakey*: a string usable as a WPA key (either between 8 and 63 characters, or 64 hex digits)
- *range* (*min*, *max*): a number in the given range (inclusive)
- *min* (*min*): a number greater than or equal to the given minimum
- *max* (*max*): a number less than or equal to the given maximum
- *irange* (*min*, *max*): an integral number in the given range (inclusive)
- *imin* (*min*): an integral number greater than or equal to the given minimum
- *imax* (*max*): an integral number less than or equal to the given maximum
- *minlength* (*min*): a string with the given minimum length
- *maxlength* (*max*): a string with the given maximum length
Differences from LuCI
---------------------
- LuCI's *SimpleForm* and *SimpleSection* are called *Form* and *Section*, respectively
- Is it not possible to add options to a *Form* directly, a *Section* must always
be created explicitly
- Many of LuCI's CBI classes have been removed, most importantly the *Map*
- The *rmempty* option attribute does not exist, use *optional* instead
- Only the described data types are supported
- Form handlers work completely differently (in particular, a *Form*'s *handle*
method should usually not be overridden in *gluon-web*)