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 899 additions and 534 deletions
contrib/run_qemu.sh 0 → 100755
View file @ b9a90f4f
#!/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 @ b9a90f4f
......@@ -2,7 +2,7 @@
set -e
if [ $# -ne 2 -o "-h" = "$1" -o "--help" = "$1" -o ! -r "$1" -o ! -r "$2" ]; then
if [ $# -ne 2 ] || [ "-h" = "$1" ] || [ "--help" = "$1" ] || [ ! -r "$1" ] || [ ! -r "$2" ]; then
cat <<EOHELP
Usage: $0 <secret> <manifest>
......@@ -15,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
......@@ -29,11 +29,22 @@ lower="$(mktemp)"
trap 'rm -f "$upper" "$lower"' EXIT
awk 'BEGIN { sep=0 }
/^---$/ { sep=1; next }
{ if(sep==0) print > "'"$upper"'";
else print > "'"$lower"'"}' \
"$manifest"
awk 'BEGIN {
sep = 0
}
/^---$/ {
sep = 1;
next
}
{
if(sep == 0) {
print > "'"$upper"'"
} else {
print > "'"$lower"'"
}
}' "$manifest"
ecdsasign "$upper" < "$SECRET" >> "$lower"
......
contrib/sigtest.sh
View file @ b9a90f4f
#!/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 @ b9a90f4f
# 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 @ b9a90f4f
.strike {
text-decoration: line-through;
}
docs/conf.py
View file @ b9a90f4f
#!/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-2016, 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 = '2016.2+'
# The full version, including alpha/beta/rc tags.
release = '2016.2+'
# 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 @ b9a90f4f
......@@ -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,19 +33,19 @@ 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 commited on top of the `patched` branch (or existing commits
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 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.
......@@ -48,18 +53,33 @@ and you can try rebasing it onto the new `base` branch yourself and after that c
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 refresh-patches
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.
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
Lua should be used instead of sh whenever sensible. The following criteria
should be considered:
- 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
- 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
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
the code in the project is formatted in the same way. The following basic rules
apply:
- use tabs instead of spaces
- trailing whitespaces must be eliminated
- 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 @ b9a90f4f
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 @ b9a90f4f
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 @ b9a90f4f
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.
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.
.. _hardware-adding-profiles:
.. _device-class-definition:
Adding profiles
---------------
The vast majority of devices with ath9k WLAN uses the ar71xx target of LEDE.
If the hardware you want to add support for is also ar71xx, adding a new profile
is enough.
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.
Profiles are defined in ``targets/*`` in a shell-based DSL (so common shell
commands syntax like ``if`` can be used.
There are currently two devices classes defined: "standard" and "tiny". The
"tiny" class contains all devices that do not meet the following requirements:
The ``device`` command is used to define an image build for a device. It takes
two or three parameters.
- At least 7 MiB of usable firmware space
- At least 64 MiB of RAM (128MiB for devices with ath10k radio)
The first parameter defines the Gluon profile name, which is used to refer to the
device and is part of the generated image name. The profile name must be same as
the output of the following command (on the target device), so the autoupdater
can work::
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.
lua -e 'print(require("platform_info").get_image_name())'
All targets must be listed in ``target/targets.mk``.
The second parameter defines the name of the image files generated by LEDE. Usually,
it is also the LEDE profile name; for devices that still use the old image build
code, a third parameter with the LEDE profile name can be passed. The profile names
can be found in the image Makefiles in ``lede/target/linux/<target>/image/Makefile``.
The target configuration language is based on Lua, so Lua's syntax for variables
and control structures can be used.
Examples::
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:
device tp-link-tl-wr1043n-nd-v1 tl-wr1043nd-v1
device alfa-network-hornet-ub hornet-ub HORNETUB
.. code-block:: lua
Suffixes and extensions
'''''''''''''''''''''''
By default, image files are expected to have the extension ``.bin``. In addition,
the images generated by LEDE have a suffix before the extension that defaults to
``-squashfs-factory`` and ``-squashfs-sysupgrade``.
This can be changed using the ``factory`` and ``sysupgrade`` commands, either at
the top of the file to set the defaults for all images, or for a single image. There
are three forms with 0 to 2 arguments (all work with ``sysupgrade`` as well)::
factory SUFFIX .EXT
factory .EXT
factory
When only an extension is given, the default suffix is retained. When no arguments
are given, this signals that no factory (or sysupgrade) image exists.
Aliases
'''''''
Sometimes multiple models use the same LEDE images. In this case, the ``alias``
command can be used to create symlinks and additional entries in the autoupdater
manifest for the alternative models.
Standalone images
'''''''''''''''''
On targets without *per-device rootfs* support in LEDE, the commands described above
can't be used. Instead, ``factory_image`` and ``sysupgrade_image`` are used::
factory_image PROFILE IMAGE .EXT
sysupgrade_image PROFILE IMAGE .EXT
Again, the profile name must match the value printed by the aforementioned Lua
command. The image name must match the part between the target name and the extension
as generated by LEDE and is to be omitted when no such part exists.
Packages
''''''''
device('tp-link-tl-wdr3600-v1', 'tplink_tl-wdr3600-v1')
The ``packages`` command takes an arbitrary number of arguments. Each argument
defines an additional package to include in the images in addition to the default
package sets defined by LEDE. When a package name is prefixed by a minus sign, the
packages are excluded instead.
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/*``.
The ``packages`` command may be used at the top of a target definition to modify
the default package list for all images, or just for a single device (when the
target supports *per-default rootfs*).
A table of additional settings can be passed as a third argument:
.. code-block:: lua
Configuration
'''''''''''''
device('ubiquiti-edgerouter-x', 'ubnt_edgerouter-x', {
factory = false,
packages = {'-hostapd-mini'},
manifest_aliases = {
'ubnt-erx',
},
})
The ``config`` command allows to add arbitary target-specific LEDE configuration
to be emitted to ``.config``.
The supported additional settings are described in the following sections.
Notes
'''''
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/010-primary-mac``
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 a LEDE 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:
Package adjustments
'''''''''''''''''''
One package that may need adjustments for new targets is ``libplatforminfo`` (to be found in
`packages/gluon/libs/libplatforminfo <https://github.com/freifunk-gluon/packages/tree/master/libs/libplatforminfo>`_).
If the new platform works fine with the definitions found in ``default.c``, nothing needs to be done. Otherwise,
create a definition for the added target or subtarget, either by symlinking one of the files in the ``templates``
directory, or adding a new source file.
On many targets, Gluon's network setup scripts (mainly in the package ``gluon-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).
Build system support
''''''''''''''''''''
A definition for the new target must be created under ``targets``, and it must be added
to ``targets/targets.mk``. The ``GluonTarget`` macro takes one to three arguments:
the target name, the Gluon subtarget name (if the target has subtargets), and the
LEDE subtarget name (if it differs from the Gluon subtarget). The third argument
can be used to define multiple Gluon targets with different configuration for the
same LEDE target, like it is done for the ``ar71xx-tiny`` target.
After this, is should be sufficient to call ``make GLUON_TARGET=<target>`` to build the images for the new target.
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/mac_addresses.rst
View file @ b9a90f4f
......@@ -10,9 +10,9 @@ Gluon tries to solve this issue by using a hash of the primary MAC address as a
* 0: client0; WAN
* 1: mesh0
* 2: ibss0
* 2: owe0
* 3: wan_radio0 (private WLAN); batman-adv primary address
* 4: client1; LAN
* 5: mesh1
* 6: ibss1
* 6: owe1
* 7: wan_radio1 (private WLAN); mesh VPN
docs/dev/packages.rst 0 → 100644
View file @ b9a90f4f
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 @ b9a90f4f
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 @ b9a90f4f
......@@ -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
......@@ -19,14 +19,12 @@ Best practices
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 is ``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 @ b9a90f4f
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/web/config-mode.rst
View file @ b9a90f4f
......@@ -2,7 +2,7 @@ Config Mode
===========
The `Config Mode` consists of several modules that provide a range of different
condiguration options:
configuration options:
gluon-config-mode-core
This modules provides the core functionality for the config mode.
......
docs/dev/web/controller.rst
View file @ b9a90f4f
Controllers
===========
Controllers live in ``/lib/gluon/web/controller``. They define which pages ("routes")
exist under the ``/cgi-bin/gluon`` path, and what code is run when these pages are requested.
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 mostly consist of calls of the `entry` function, which each define
one route:
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)
The entry function expects 4 arguments:
*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.
......@@ -20,6 +26,7 @@ The entry function expects 4 arguments:
- `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)
......@@ -64,11 +71,10 @@ Useful functions:
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 to
- *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, potentially setting additional headers or modifying the MIME type to
accommodate browser quirks
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.
......@@ -88,9 +94,10 @@ The template renderer
The template renderer allows to render templates (views). The most useful functions
are:
- *render* (*view*, *scope*): Renders the given view, optionally passing a table
with additional variables to make available in the template.
- *render_string* (*str*, *scope*): Same as *render*, but the template is passed
- *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:
......
docs/dev/web/i18n.rst
View file @ b9a90f4f
......@@ -20,8 +20,9 @@ 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.
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:
......@@ -29,6 +30,18 @@ Example from the *gluon-config-mode-geo-location* package:
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
----------------------------------------------
......@@ -45,7 +58,7 @@ script in the ``contrib`` directory:
The same command can be run again to update the template.
In addition, some additions to the Makefile must be made. Instead of LEDE's default *package.mk*,
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::
......@@ -92,5 +105,5 @@ 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*, after a human-readable
language name has been defined in the same file.
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
View file @ b9a90f4f
Models
======
Models are defined in ``/lib/gluon/web/model``. Each model defines one or more
forms to display on a page, and how the submitted form data is handled.
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:
......@@ -21,7 +26,7 @@ Let's start with an example:
return f
The toplevel element of a model is always a *Form*, but it is also possible for
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
......@@ -46,14 +51,14 @@ Classes and methods
- *Form:write* ()
Is called after the form has beed submitted (but only if the data is valid). It
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 to anything, but it can be
The default implementation of *write* doesn't do anything, but it can be
overridden.
- *Section* (usually instanciated through *Form:section*)
- *Section* (usually instantiated through *Form:section*)
- *Section:option* (*type*, *id*, *title*, *description*)
......
docs/dev/web/view.rst
View file @ b9a90f4f
Views
=====
The template parser reads views from ``/lib/gluon/web/view``. Writing own view
should be avoided in favour of using :doc:`model` with their predefined views.
The template parser reads views from the ``view`` subdirectory of a
gluon-web application (``/lib/gluon/config-mode/view`` for the config mode,
``lib/gluon/status-page/view`` for the status page).
Writing own views should usually be avoided in favour of using :doc:`model`
with their predefined views.
Views are partial HTML pages, with additional template tags that allow
to embed Lua code and translation strings. The following tags are defined:
- ``<%`` ... ``%>`` evaluates the enclosed Lua expression.
- ``<%=`` ... ``%>`` evaluates the enclosed Lua expression and prints its value.
- ``<%|`` ... ``%>`` evaluates the enclosed Lua expression and prints its value.
- ``<%=`` ... ``%>`` evaluates the enclosed Lua expression and prints its value
*without escaping HTML entities*. This is useful when the value contains HTML code.
- ``<%+`` ... ``%>`` includes another template.
- ``<%:`` ... ``%>`` translates the enclosed string using the loaded i18n catalog.
- ``<%_`` ... ``%>`` translates the enclosed string *without escaping HTML entities*
......@@ -52,4 +57,4 @@ variables and functions should always be available for the embedded Lua code:
Use ``node(unpack(request))`` to get the node for the current page.
- *pcdata* (*str*): Escapes HTML entities in the passed string.
- *urlencode* (*str*): Escapes the passed string for use in an URL.
- *translate*, *_translate* and *translatef*: see :doc:`i18n`
- *translate*, *_translate*, *translatef* and *i18n*: see :doc:`i18n`