171b484735
This commit basically does two things: it urges users always to use an own git repository to manage the site configuration, and it removed all mentions of "communities" from the "Getting started" page, as it was too Freifunk-specific. Other documentation pages (especially the site configuration docs) should probably be adjusted as well.
183 lines
6.4 KiB
ReStructuredText
183 lines
6.4 KiB
ReStructuredText
Getting Started
|
|
===============
|
|
|
|
Selecting the right version
|
|
---------------------------
|
|
|
|
Gluon's releases are managed using `Git tags`_. If you are just getting
|
|
started with Gluon we recommend to use the latest stable release of Gluon.
|
|
|
|
Take a look at the `list of gluon releases`_ and notice the latest release,
|
|
e.g. *v2014.3*. Always get Gluon using git and don't try to download it
|
|
as a Zip archive as the archive will be missing version information.
|
|
|
|
Please keep in mind that there is no "default Gluon" build; a site configuration
|
|
is required to adjust Gluon to your needs. Due to new features being added (or
|
|
sometimes being removed) the format of the site configuration changes slightly
|
|
between releases. Please refer to our release notes for instructions to update
|
|
an old site configuration to a newer release of Gluon.
|
|
|
|
An example configuration can be found in the Gluon repository at *docs/site-example/*.
|
|
|
|
.. _Git tags: http://git-scm.com/book/en/Git-Basics-Tagging
|
|
.. _list of gluon releases: https://github.com/freifunk-gluon/gluon/releases
|
|
|
|
Dependencies
|
|
------------
|
|
To build Gluon, several packages need to be installed on the system. On a
|
|
freshly installed Debian Wheezy system the following packages are required:
|
|
|
|
* `git` (to get Gluon and other dependencies)
|
|
* `subversion`
|
|
* `python` (Python 3 doesn't work)
|
|
* `build-essential`
|
|
* `gawk`
|
|
* `unzip`
|
|
* `libncurses-dev` (actually `libncurses5-dev`)
|
|
* `libz-dev` (actually `zlib1g-dev`)
|
|
* `libssl-dev`
|
|
|
|
|
|
Building the images
|
|
-------------------
|
|
|
|
To build Gluon, first check out the repository. Replace *RELEASE* with the
|
|
version you'd like to checkout, e.g. *v2015.1*.
|
|
|
|
::
|
|
|
|
git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE
|
|
|
|
This command will create a directory named *gluon/*.
|
|
It might also tell a scary message about being in a *detached state*.
|
|
**Don't panic!** Everything's fine.
|
|
Now, enter the freshly created directory::
|
|
|
|
cd gluon
|
|
|
|
It's time to add (or create) your site configuration. If you already
|
|
have a site repository, just clone it::
|
|
|
|
git clone https://github.com/freifunk-duckburg/site-ffdb.git site
|
|
|
|
If you want to build a new site, create a new git repository *site/*::
|
|
|
|
mkdir site
|
|
cd site
|
|
git init
|
|
|
|
Copy *site.conf*, *site.mk* and *i18n* from *docs/site-example*::
|
|
|
|
cp ../docs/site-example/site.conf .
|
|
cp ../docs/site-example/site.mk .
|
|
cp -r ../docs/site-example/i18n .
|
|
|
|
Edit these files as you see fit and commit them into the site repository.
|
|
Extensive documentation about the site configuration can be found at:
|
|
:doc:`site`. The
|
|
site directory should always be a git repository by itself; committing site-specific files
|
|
to the Gluon main repository should be avoided, as it will make updates more complicated.
|
|
|
|
Next go back to the top-level Gluon directory and build Gluon::
|
|
|
|
cd ..
|
|
make update # Get other repositories used by Gluon
|
|
make GLUON_TARGET=ar71xx-generic # Build Gluon
|
|
|
|
When calling make, the OpenWrt build environment is prepared/updated.
|
|
In case of errors read the messages carefully and try to fix the stated issues (e.g. install tools not available yet).
|
|
|
|
``ar71xx-generic`` is the most common target and will generate images for most of the supported hardware.
|
|
To see a complete list of supported targets, call ``make`` without setting ``GLUON_TARGET``.
|
|
|
|
The built images can be found in the directory `output/images`. Of these, the factory
|
|
images are to be used when flashing from the original firmware a device came with,
|
|
and sysupgrade is to upgrade from other versions of Gluon or any other OpenWRT-based
|
|
system.
|
|
|
|
You should reserve about 10GB of disk space for each `GLUON_TARGET`.
|
|
|
|
There are two levels of `make clean`::
|
|
|
|
make clean GLUON_TARGET=ar71xx-generic
|
|
|
|
will ensure all packages are rebuilt for a single target; this is what you normally want to do after an update.
|
|
|
|
::
|
|
|
|
make dirclean
|
|
|
|
will clean the entire tree, so the toolchain will be rebuilt as well, which is
|
|
not necessary in most cases, and will take a while.
|
|
|
|
|
|
opkg repositories
|
|
-----------------
|
|
|
|
Gluon is mostly compatible with OpenWrt, so the normal OpenWrt package repositories
|
|
can be used for Gluon as well. It is advisable to setup a mirror or reverse proxy
|
|
reachable over IPv6 and add it to ``site.conf`` as http://downloads.openwrt.org/ does
|
|
not support IPv6.
|
|
|
|
This is not true for kernel modules; the Gluon kernel is incompatible with the
|
|
kernel of the default OpenWrt images. Therefore, Gluon will not only generate images,
|
|
but also an opkg repositoy containing all kernel modules provided by OpenWrt/Gluon
|
|
for the kernel of the generated images.
|
|
|
|
Signing keys
|
|
............
|
|
|
|
Gluon does not support HTTPS for downloading packages; fortunately, opkg deploys
|
|
public-key cryptography to ensure package integrity.
|
|
|
|
The Gluon images will contain two public keys: the official OpenWrt signing key
|
|
(to allow installing userspace packages) and a Gluon-specific key (which is used
|
|
to sign the generated module repository).
|
|
|
|
By default, Gluon will handle the generation and handling of the keys itself.
|
|
When making firmware releases based on Gluon, it might make sense to store
|
|
the keypair, so updating the module repository later is possible.
|
|
|
|
The location the keys are stored at and read from can be changed
|
|
(see :ref:`getting-started-environment-variables`). To only generate the keypair
|
|
at the configured location without doing a full build, use ``make create-key``.
|
|
|
|
.. _getting-started-environment-variables:
|
|
|
|
Environment variables
|
|
---------------------
|
|
|
|
Gluon's build process can be controlled by various environment variables.
|
|
|
|
GLUON_SITEDIR
|
|
Path to the site configuration. Defaults to ``site``.
|
|
|
|
GLUON_BUILDDIR
|
|
Working directory during build. Defaults to ``build``.
|
|
|
|
GLUON_OPKG_KEY
|
|
Path key file used to sign the module opkg repository. Defaults to ``$(GLUON_BULDDIR)/gluon-opkg-key``.
|
|
|
|
The private key will be stored as ``$(GLUON_OPKG_KEY)``, the public key as ``$(GLUON_OPKG_KEY).pub``.
|
|
|
|
GLUON_OUTPUTDIR
|
|
Path where output files will be stored. Defaults to ``output``.
|
|
|
|
GLUON_IMAGEDIR
|
|
Path where images will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/images``.
|
|
|
|
GLUON_MODULEDIR
|
|
Path where the kernel module opkg repository will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/modules``.
|
|
|
|
|
|
So all in all, to update and rebuild a Gluon build tree, the following commands should be used (repeat the
|
|
``make clean`` and ``make`` for all targets you want to build):
|
|
|
|
::
|
|
|
|
git pull
|
|
(cd site && git pull)
|
|
make update
|
|
make clean GLUON_TARGET=ar71xx-generic
|
|
make GLUON_TARGET=ar71xx-generic
|