nils/gluon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: move from README to docs/

Browse Source
This commit is contained in:
Nils Schneider 2014-07-09 12:43:10 +02:00
parent 9f8afd49fa
commit 38bac6a6ad
6 changed files with 149 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@ -1,100 +1,8 @@
To build Gluon, after checking out the repository change to the source root directory Documentation (incomplete at this time, contribute if you can!) may be found at
to perform the following commands: http://gluon.readthedocs.org/
git clone git://github.com/freifunk-gluon/site-ffhl.git site # Get the Freifunk Lübeck site repository - or use your own! If you're new to Gluon and ready to get your feet wet, have a look at the
make update # Get other repositories used by Gluon [Getting Started Guide]([http://gluon.readthedocs.org/en/latest/user/getting_started.html).
make # Build Gluon
When calling make, the OpenWRT build environment is prepared/updated. To rebuild
the images only, just use:
make images
The built images can be found in the directory `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.
For the build reserve 6GB of disk space. The build requires packages
for `subversion`, ncurses headers (`libncurses-dev`) and zlib headers
(`libz-dev`).`
There are two levels of `make clean`:
make clean
will ensure all packages are rebuilt; 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.
So all in all, to update and rebuild a Gluon build tree, the following commands should be used:
git pull
(cd site && git pull)
make update
make clean
make
# The autoupdater
Gluon contains an automatic update system which can be configured in the site configuration.
By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
during development), but it can be enabled by setting the variable GLUON_BRANCH when building
to override the default branch set in the set in the site configuration.
A manifest file for the updater can be generated with `make manifest`. A signing script (using
ecdsautils) can by found in the `contrib` directory.
A fully automated nightly build could use the following commands:
git pull
(cd site && git pull)
make update
make clean
make -j5 GLUON_BRANCH=experimental
make manifest GLUON_BRANCH=experimental
contrib/sign.sh $SECRETKEY images/sysupgrade/experimental.manifest
cp -r images /where/to/put/this/experimental
mv /where/to/put/this/experimental/experimental.manifest /where/to/put/this/experimental/manifest
# Development
**Gluon IRC channel: `#gluon` in hackint** **Gluon IRC channel: `#gluon` in hackint**
To update the repositories used by Gluon, just adjust the commit IDs in `modules` and
rerun
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`.
make unpatch
sets the repositories to the `base` branch,
make patch
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.
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
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.
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!

63
docs/dev/basics.rst Normal file
View File

@ -0,0 +1,63 @@
Development Basics
==================
Gluon's source is kept in `git repositories`_ at GitHub.
.. _git repositories: https://github.com/freifunk-gluon
Bug Tracker
-----------
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 on hackint: irc://irc.hackint.org/#gluon
Working with repositories
-------------------------
To update the repositories used by Gluon, just adjust the commit IDs in `modules` and
rerun
::
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`.
::
make unpatch
sets the repositories to the `base` branch,
::
make patch
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.
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
::
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.
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!

20
docs/dev/contribute.rst
View File

@ -1,20 +0,0 @@
Contributing to Gluon
=====================
Gluon's source is kept in `git repositories`_ at GitHub.
.. _git repositories: https://github.com/freifunk-gluon
Bug Tracker
-----------
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 on hackint: irc://irc.hackint.org/#gluon

31
docs/features/autoupdater.rst
View File

@ -1,6 +1,33 @@
Autoupdater Autoupdater
=========== ===========
Gluon contains an automatic update system which can be configured in the site configuration.
Building Images
---------------
By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
during development), but it can be enabled by setting the variable GLUON_BRANCH when building
to override the default branch set in the set in the site configuration.
A manifest file for the updater can be generated with `make manifest`. A signing script (using
ecdsautils) can by found in the `contrib` directory.
A fully automated nightly build could use the following commands:
::
git pull
(cd site && git pull)
make update
make clean
make -j5 GLUON_BRANCH=experimental
make manifest GLUON_BRANCH=experimental
contrib/sign.sh $SECRETKEY images/sysupgrade/experimental.manifest
cp -r images /where/to/put/this/experimental
mv /where/to/put/this/experimental/experimental.manifest /where/to/put/this/experimental/manifest
Infrastructure Infrastructure
-------------- --------------
@ -28,6 +55,8 @@ The server should be available via IPv6.
Command Line Command Line
------------ ------------
These commands can be used on a node.
:: ::
# Update with some probability # Update with some probability
@ -37,3 +66,5 @@ Command Line
# Force Update Check # Force Update Check
autoupdater -f autoupdater -f

2
docs/index.rst
View File

@ -48,7 +48,7 @@ Developer Documentation
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
dev/contribute dev/basics
dev/architecture dev/architecture
dev/repositories dev/repositories
dev/packages dev/packages

55
docs/user/getting_started.rst
View File

@ -1,10 +1,55 @@
Getting Started Getting Started
=============== ===============
To build Gluon, after checking out the repository change to the source root directory
to perform the following commands:
:: ::
git clone https://github.com/freifunk-gluon/gluon.git git clone git://github.com/freifunk-gluon/site-ffhl.git site # Get the Freifunk Lübeck site repository - or use your own!
cd gluon make update # Get other repositories used by Gluon
git clone git://github.com/freifunk-gluon/site-ffhl.git site make # Build Gluon
make update
make When calling make, the OpenWRT build environment is prepared/updated. To rebuild
the images only, just use:
::
make images
The built images can be found in the directory `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.
For the build reserve 6GB of disk space. The build requires packages
for `subversion`, ncurses headers (`libncurses-dev`) and zlib headers
(`libz-dev`).
There are two levels of `make clean`:
::
make clean
will ensure all packages are rebuilt; 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.
So all in all, to update and rebuild a Gluon build tree, the following commands should be used:
::
git pull
(cd site && git pull)
make update
make clean
make