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
|
||||
to perform the following commands:
|
||||
Documentation (incomplete at this time, contribute if you can!) may be found at
|
||||
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!
|
||||
make update # Get other repositories used by Gluon
|
||||
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
|
||||
If you're new to Gluon and ready to get your feet wet, have a look at the
|
||||
[Getting Started Guide]([http://gluon.readthedocs.org/en/latest/user/getting_started.html).
|
||||
|
||||
**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
63
docs/dev/basics.rst
Normal 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!
|
||||
@ -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
|
||||
===========
|
||||
|
||||
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
|
||||
--------------
|
||||
|
||||
@ -28,6 +55,8 @@ The server should be available via IPv6.
|
||||
Command Line
|
||||
------------
|
||||
|
||||
These commands can be used on a node.
|
||||
|
||||
::
|
||||
|
||||
# Update with some probability
|
||||
@ -37,3 +66,5 @@ Command Line
|
||||
|
||||
# Force Update Check
|
||||
autoupdater -f
|
||||
|
||||
|
||||
|
||||
@ -48,7 +48,7 @@ Developer Documentation
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
dev/contribute
|
||||
dev/basics
|
||||
dev/architecture
|
||||
dev/repositories
|
||||
dev/packages
|
||||
|
||||
@ -1,10 +1,55 @@
|
||||
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
|
||||
cd gluon
|
||||
git clone git://github.com/freifunk-gluon/site-ffhl.git site
|
||||
git clone git://github.com/freifunk-gluon/site-ffhl.git site # Get the Freifunk Lübeck site repository - or use your own!
|
||||
make update # Get other repositories used by Gluon
|
||||
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
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user