docs: move from README to docs/
This commit is contained in:
Nils Schneider
parent
9f8afd49fa
commit
38bac6a6ad
100
README.md
100
README.md
|
|
@ -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!
|
|
||||||
|
|
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Reference in New Issue