manual: convert existing documentation to the asciidoc format

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Acked-by: Luca Ceresoli <luca@lucaceresoli.net>
Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Reviewed-by: "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>

1 files changed, 75 insertions, 0 deletions

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
new file mode 100644
index 000000000..058ebad1c
--- /dev/null
+++ b/docs/manual/adding-packages-directory.txt
@@ -0,0 +1,75 @@
+Package directory
+-----------------
+
+First of all, create a directory under the +package+ directory for
+your software, for example +libfoo+.
+
+Some packages have been grouped by topic in a sub-directory:
++multimedia+, +java+, +x11r7+, and +games+. If your package fits in
+one of these categories, then create your package directory in these.
+
++Config.in+ file
+~~~~~~~~~~~~~~~~
+
+Then, create a file named +Config.in+. This file will contain the
+option descriptions related to our +libfoo+ software that will be used
+and displayed in the configuration tool. It should basically contain :
+
+---------------------------
+config BR2_PACKAGE_LIBFOO
+	bool "libfoo"
+	help
+	  This is a comment that explains what libfoo is.
+
+	  http://foosoftware.org/libfoo/
+---------------------------
+
+Of course, you can add other options to configure particular things in
+your software. You can look at examples in other packages. The syntax
+of the +Config.in+ file is the same as the one for the kernel Kconfig
+file. The documentation for this syntax is available at
+http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt[]
+
+Finally you have to add your new +libfoo/Config.in+ to
++package/Config.in+ (or in a category subdirectory if you decided to
+put your package in one of the existing categories). The files
+included there are 'sorted alphabetically' per category and are 'NOT'
+supposed to contain anything but the 'bare' name of the package.
+
+--------------------------
+source "package/libfoo/Config.in"
+--------------------------
+
+The +.mk+ file
+~~~~~~~~~~~~~~
+
+Finally, here's the hardest part. Create a file named +libfoo.mk+. It
+describes how the package should be downloaded, configured, built,
+installed, etc.
+
+Depending on the package type, the +.mk+ file must be written in a
+different way, using different infrastructures:
+
+* *Makefiles for generic packages* (not using autotools): These are
+  based on an infrastructure similar to the one used for
+  autotools-based packages, but requires a little more work from the
+  developer. They specify what should be done for the configuration,
+  compilation, installation and cleanup of the package. This
+  infrastructure must be used for all packages that do not use the
+  autotools as their build system. In the future, other specialized
+  infrastructures might be written for other build systems.  We cover
+  them through in a xref:gentargets-tutorial[tutorial] and a
+  xref:gentargets-reference[reference].
+
+* *Makefiles for autotools-based software* (autoconf, automake, etc.):
+  We provide a dedicated infrastructure for such packages, since
+  autotools is a very common build system. This infrastructure 'must'
+  be used for new packages that rely on the autotools as their build
+  system. We cover them through a xref:autotargets-tutorial[tutorial]
+  and xref:autotargets-reference[reference].
+
+* *Hand-written Makefiles:* These are currently obsolete, and no new
+  manual Makefiles should be added. However, since there are still
+  many of them in the tree, we keep them documented in a
+  xref:handwritten-tutorial[tutorial].
+