getting_started.rst 3.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117
  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 if 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. Building the image
  17. ------------------
  18. .. note:: Make sure you have configured your `Git identity`_.
  19. If you neglect this, you'll get strange error messages.
  20. .. _Git identity: http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup#Your-Identity
  21. To build Gluon, first check out the repository. Replace *RELEASE* with the
  22. version you'd like to checkout, e.g. *v2014.3*.
  23. ::
  24. git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE
  25. This command will create a directory named *gluon/*.
  26. It might also tell a scary message about being in a *detached state*.
  27. **Don't panic!** Everything's fine.
  28. Now, enter the freshly created directory:
  29. ::
  30. cd gluon
  31. It's time to add (or create) your site configuration.
  32. So let's create the directory *site/*:
  33. ::
  34. mkdir site
  35. cd site
  36. Copy *site.conf* and *site.mk* from *docs/site-example*:
  37. ::
  38. cp ../docs/site-example/site.conf .
  39. cp ../docs/site-example/site.mk .
  40. .. note:: On **v2014.3**, take both files from
  41. https://github.com/freifunk-gluon/gluon/tree/2014.3.x/docs/site-example
  42. Edit both files to match your community, then go back to the top-level Gluon
  43. directory and build Gluon:
  44. ::
  45. cd ..
  46. make update # Get other repositories used by Gluon
  47. make # Build Gluon
  48. When calling make, the OpenWRT build environment is prepared/updated.
  49. In case of errors read the messages carefully and try to fix the stated issues (e.g. install tools not available yet).
  50. To rebuild the images only, just use:
  51. ::
  52. make images
  53. The built images can be found in the directory `images`. Of these, the factory
  54. images are to be used when flashing from the original firmware a device came with,
  55. and sysupgrade is to upgrade from other versions of Gluon or any other OpenWRT-based
  56. system.
  57. For the build reserve 6GB of disk space. The build requires packages
  58. for `subversion`, ncurses headers (`libncurses-dev`) and zlib headers
  59. (`libz-dev`).
  60. There are two levels of `make clean`:
  61. ::
  62. make clean
  63. will ensure all packages are rebuilt; this is what you normally want to do after an update.
  64. ::
  65. make dirclean
  66. will clean the entire tree, so the toolchain will be rebuilt as well, which is
  67. not necessary in most cases, and will take a while.
  68. So all in all, to update and rebuild a Gluon build tree, the following commands should be used:
  69. ::
  70. git pull
  71. (cd site && git pull)
  72. make update
  73. make clean
  74. make