From 38bac6a6adbaf026028e79058ed729e58d01d26f Mon Sep 17 00:00:00 2001 From: Nils Schneider Date: Wed, 9 Jul 2014 12:43:10 +0200 Subject: [PATCH] docs: move from README to docs/ --- README.md | 100 ++-------------------------------- docs/dev/basics.rst | 63 +++++++++++++++++++++ docs/dev/contribute.rst | 20 ------- docs/features/autoupdater.rst | 31 +++++++++++ docs/index.rst | 2 +- docs/user/getting_started.rst | 55 +++++++++++++++++-- 6 files changed, 149 insertions(+), 122 deletions(-) create mode 100644 docs/dev/basics.rst delete mode 100644 docs/dev/contribute.rst diff --git a/README.md b/README.md index 7dfb55f3..d2586454 100644 --- a/README.md +++ b/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! diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst new file mode 100644 index 00000000..7e7d9f58 --- /dev/null +++ b/docs/dev/basics.rst @@ -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! diff --git a/docs/dev/contribute.rst b/docs/dev/contribute.rst deleted file mode 100644 index 600888f3..00000000 --- a/docs/dev/contribute.rst +++ /dev/null @@ -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 diff --git a/docs/features/autoupdater.rst b/docs/features/autoupdater.rst index c0777ebd..c7257284 100644 --- a/docs/features/autoupdater.rst +++ b/docs/features/autoupdater.rst @@ -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 + + diff --git a/docs/index.rst b/docs/index.rst index 2decc906..732fb26a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,7 +48,7 @@ Developer Documentation .. toctree:: :maxdepth: 2 - dev/contribute + dev/basics dev/architecture dev/repositories dev/packages diff --git a/docs/user/getting_started.rst b/docs/user/getting_started.rst index b4986ae7..62e26d1e 100644 --- a/docs/user/getting_started.rst +++ b/docs/user/getting_started.rst @@ -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 - make update - make + 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 + +