docs/Modules.md

   1 # Reference: LuCI Modules
   2
   3 See [online wiki](https://github.com/openwrt/luci/wiki/Modules) for latest version.
   4
   5 ## Categories
   6
   7 The LuCI modules are divided into several category directories, namely:
   8 * applications - Single applications or plugins for other modules
   9 * i18n - Translation files
  10 * libs - libraries of Luci
  11 * modules - main modules of Luci itself
  12 * protocols - network related plugins
  13 * themes - Frontend themes
  14
  15 Each module goes into a subdirectory of this category-directories.
  16
  17 ## Module directory
  18 The contents of a module directory are as follows:
  19
  20 ### Makefile
  21 This is the module's makefile. If the module just contains Lua sourcecode or resources then the following Makefile should suffice.
  22 ```Makefile
  23 include $(TOPDIR)/rules.mk
  24
  25 LUCI_TITLE:=Title of my example applications
  26 LUCI_DEPENDS:=+some-package +libsome-library +luci-app-anotherthing
  27
  28 include ../../luci.mk
  29
  30 # call BuildPackage - OpenWrt buildroot signature
  31 ```
  32
  33 If you have C(++) code in your module you should include a `src/` subdirectory containing another Makefile supporting a `clean`, a `compile` and an `install` target.
  34 The `install` target should deploy its files relative to the predefined `$(DESTDIR)` variable, e.g.
  35 ```
  36 mkdir -p $(DESTDIR)/usr/bin; cp myexecutable $(DESTDIR)/usr/bin/myexecutable
  37 ```
  38
  39 ### src
  40 The `src` directory is reserved for C sourcecode.
  41
  42 ### luasrc
  43 `luasrc` contains all Lua sourcecode files. These will automatically be stripped or compiled depending on the Make target and are installed in the LuCI installation directory.
  44
  45 ### lua
  46 `lua` is equivalent to `luasrc` but containing Lua files will be installed in the Lua document root.
  47
  48 ### htdocs
  49 All files under `htdocs` will be copied to the document root of the target webserver.
  50
  51 ### root
  52 All directories and files under `root` will be copied to the installation target as they are.
  53
  54 ### dist
  55 `dist` is reserved for the builder to create a working installation tree that will represent the filesystem on the target machine.
  56 **DO NOT** put any files there as they will get deleted.
  57
  58 ### ipkg
  59 `ipkg` contains IPKG package control files, like `preinst`, `posinst`, `prerm`, `postrm`. `conffiles`.
  60 See IPKG documentation for details.
  61
  62
  63 ## OpenWRT feed integration
  64 If you want to add your module to the LuCI OpenWRT feed you have to add several sections to the `contrib/package/luci/Makefile`.
  65
  66 For a Web UI applications this is:
  67
  68 A package description:
  69 ```Makefile
  70 define Package/luci-app-YOURMODULE
  71   $(call Package/luci/webtemplate)
  72   DEPENDS+=+some-package +some-other-package
  73   TITLE:=SHORT DESCRIPTION OF YOURMODULE
  74 endef
  75 ```
  76
  77 A package installation target:
  78 ```Makefile
  79 define Package/luci-app-YOURMODULE/install
  80   $(call Package/luci/install/template,$(1),applications/YOURMODULE)
  81 endef
  82 ```
  83
  84 A module build instruction:
  85 ```Makefile
  86 ifneq ($(CONFIG_PACKAGE_luci-app-YOURMODULE),)
  87   PKG_SELECTED_MODULES+=applications/YOURMODULE
  88 endif
  89 ```
  90
  91 A build package call:
  92 ```Makefile
  93 $(eval $(call BuildPackage,luci-app-YOURMODULE))
  94 ```