openadk/docs/writing-rules.txt

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

Coding style
------------

Overall, these coding style rules are here to help you to add new files in
OpenADK or refactor existing ones.

[[writing-rules-config-in]]

+Config.in+
~~~~~~~~~~~

+Config.in+ files contain entries for almost anything configurable in
OpenADK. Mostly all Config.in files for packages are autogenerated and
should not be manually edited. The following rules apply for the top level
Config.in, for the files in target/config and target/linux/config.

An entry has the following pattern:

---------------------
config ADK_TARGET_FOO
	bool "foo"
	depends on ADK_PACKAGE_LIBBAZ
	select BR2_PACKAGE_LIBBAR
	help
	  This is a comment that explains what foo is.

	  http://foo.org/foo/
---------------------

* The +bool+, +depends on+, +select+ and +help+ lines are indented
  with one tab.

* The help text itself should be indented with one tab and two
  spaces.

The +Config.in+ files are the input for the configuration tool
used in OpenADK, which is the regular _Kconfig_. For further
details about the _Kconfig_ language, refer to
http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].

[[writing-rules-mk]]

+Makefile+
~~~~~~~~~~

* Header: The file starts with a license header.
+
---------------------
# This file is part of the OpenADK project. OpenADK is copyrighted
# material, please see the LICENCE file in the top-level directory.
---------------------
+
* Assignment: use +=+ followed by two tabs:
+
---------------------
PKG_VERSION:=		1.0
PKG_BUILDDEP+=		libfoo
---------------------
+

* Indentation: use tab only:
+
---------------------
libfoo-install:
	$(CP) $(WRKINST)/usr/lib/libfoo*.so* \
		$(IDIR_LIBFOO)/usr/lib
---------------------
+

* Optional dependency:

** Prefer multi-line syntax.
---------------------
ifeq ($(ADK_PACKAGE_LIBFOO_WITH_PYTHON),y)
CONFIGURE_ARGS+=	--with-python-support
else
CONFIGURE_ARGS+=	--without-python-support
endif
---------------------

Documentation
~~~~~~~~~~~~~

The documentation uses the
http://www.methods.co.nz/asciidoc/[asciidoc] format.

For further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
syntax, refer to http://www.methods.co.nz/asciidoc/userguide.html[].