getting_started.rst 4.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139
  1. Getting Started
  2. ===============
  3. Selecting the right version
  4. ---------------------------
  5. Gluon's releases are managed using `Git tags`_. If you're a community getting
  6. started with Gluon we recommend to use the latest stable release of Gluon.
  7. Take a look at the `list of gluon releases`_ and notice the latest release,
  8. e.g. *v2014.3*.
  9. Please keep in mind that a matching site configuration for your community
  10. is required. Due to new features being added (or sometimes being removed)
  11. the format of the site configuration changes slightly between releases.
  12. Recent releases (starting with *v2014.3.1*) will come with an example
  13. configuration located in *docs/site-example/*.
  14. .. _Git tags: http://git-scm.com/book/en/Git-Basics-Tagging
  15. .. _list of gluon releases: https://github.com/freifunk-gluon/gluon/releases
  16. Dependencies
  17. ------------
  18. To build Gluon, several packages need to be installed on the system. On a
  19. freshly installed Debian Wheezy system the following packages are required:
  20. * `git` (to get Gluon and other dependencies)
  21. * `subversion`
  22. * `python` (Python 3 doesn't work)
  23. * `build-essential`
  24. * `gawk`
  25. * `unzip`
  26. * `libncurses-dev` (actually `libncurses5-dev`)
  27. * `libz-dev` (actually `zlib1g-dev`)
  28. * `libssl-dev`
  29. Building the images
  30. -------------------
  31. To build Gluon, first check out the repository. Replace *RELEASE* with the
  32. version you'd like to checkout, e.g. *v2015.1*.
  33. ::
  34. git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE
  35. This command will create a directory named *gluon/*.
  36. It might also tell a scary message about being in a *detached state*.
  37. **Don't panic!** Everything's fine.
  38. Now, enter the freshly created directory:
  39. ::
  40. cd gluon
  41. It's time to add (or create) your site configuration.
  42. So let's create the directory *site/*:
  43. ::
  44. mkdir site
  45. cd site
  46. Copy *site.conf*, *site.mk* and *i18n* from *docs/site-example*:
  47. ::
  48. cp ../docs/site-example/site.conf .
  49. cp ../docs/site-example/site.mk .
  50. cp -r ../docs/site-example/i18n .
  51. Edit these files to match your community, then go back to the top-level Gluon
  52. directory and build Gluon:
  53. ::
  54. cd ..
  55. make update # Get other repositories used by Gluon
  56. make GLUON_TARGET=ar71xx-generic # Build Gluon
  57. When calling make, the OpenWrt build environment is prepared/updated.
  58. In case of errors read the messages carefully and try to fix the stated issues (e.g. install tools not available yet).
  59. ``ar71xx-generic`` is the most common target and will generated images for most of the supported hardware.
  60. To see a complete list of supported targets, call ``make`` without setting ``GLUON_TARGET``.
  61. The built images can be found in the directory `output/images`. Of these, the factory
  62. images are to be used when flashing from the original firmware a device came with,
  63. and sysupgrade is to upgrade from other versions of Gluon or any other OpenWRT-based
  64. system.
  65. You should reserve about 10GB of disk space for each `GLUON_TARGET`.
  66. There are two levels of `make clean`:
  67. ::
  68. make clean GLUON_TARGET=ar71xx-generic
  69. will ensure all packages are rebuilt for a single target; this is what you normally want to do after an update.
  70. ::
  71. make dirclean
  72. will clean the entire tree, so the toolchain will be rebuilt as well, which is
  73. not necessary in most cases, and will take a while.
  74. Environment variables
  75. ---------------------
  76. Gluon's build process can be controlled by various environment variables.
  77. GLUON_SITEDIR
  78. Path to the site configuration. Defaults to ``site/``.
  79. GLUON_BUILDDIR
  80. Working directory during build. Defaults to ``build/``.
  81. GLUON_OUTPUTDIR
  82. Path where output files will be stored. Defaults to ``output/``.
  83. GLUON_IMAGEDIR
  84. Path where images will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/images/``.
  85. So all in all, to update and rebuild a Gluon build tree, the following commands should be used (repeat the
  86. ``make clean`` and ``make`` for all targets you want to build):
  87. ::
  88. git pull
  89. (cd site && git pull)
  90. make update
  91. make clean GLUON_TARGET=ar71xx-generic
  92. make GLUON_TARGET=ar71xx-generic