From b8f201b00198207cbf4959f8f209bb2fa302515c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Fri, 28 Oct 2016 16:40:48 +0200 Subject: doc: Clarify application directory structure --- system/doc/design_principles/applications.xml | 160 +++++++++++++++++++++----- 1 file changed, 132 insertions(+), 28 deletions(-) (limited to 'system/doc') diff --git a/system/doc/design_principles/applications.xml b/system/doc/design_principles/applications.xml index 0a1b65ea8e..c673fde07e 100644 --- a/system/doc/design_principles/applications.xml +++ b/system/doc/design_principles/applications.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + Applications @@ -172,31 +172,136 @@ ch_app:stop([])
- - Directory Structure -

When packaging code using systools, the code for each - application is placed in a separate directory, - lib/Application-Vsn, where Vsn is the version number.

-

This can be useful to know, even if systools is not used, - since Erlang/OTP is packaged according to the OTP principles - and thus comes with this directory structure. The code server - (see the code(3) manual page in Kernel) automatically - uses code from - the directory with the highest version number, if more than one - version of an application is present.

-

The application directory structure can also be used in the - development environment. The version number can then - be omitted from the name.

-

The application directory has the following sub-directories:

- - src - Contains the Erlang source code. - ebin - Contains the Erlang object code, the - beam files. The .app file is also placed here. - priv - Used for application specific files. For - example, C executables are placed here. The function - code:priv_dir/1 is to be used to access this directory. - include - Used for include files. - + + Directory Structure +

When packaging code using systools, the code for each + application is placed in a separate directory, + lib/Application-Vsn, where Vsn is the version number.

+

This can be useful to know, even if systools is not used, + since Erlang/OTP is packaged according to the OTP principles + and thus comes with a specific directory structure. The code server + (see the code(3) manual + page in Kernel) automatically uses code from + the directory with the highest version number, if more than one + version of an application is present.

+
+ Directory Structure guidelines for a Development Environment +

Any directory structure for development will suffice as long as the released directory structure + adhere to the description below, + but it is encouraged that the same directory structure + also be used in a development environment. The version number should be omitted from the + application directory name since this is an artifact of the release step. +

+

Some sub-directories are required. Some sub-directories are optional, meaning that it should + only be used if the application itself requires it. Finally, some sub-directories are recommended, + meaning it is encouraged that it is used and used as described here. For example, both documentation + and tests are encouraged to exist in an application for it to be deemed a proper OTP application.

+ + ─ ${application} +   ├── doc + │   ├── internal + │   ├── examples + │   └── src +   ├── include +   ├── priv +   ├── src + │   └── ${application}.app.src +   └── test + + + src - Required. Contains the Erlang source code, the source of the .app file + and internal include files used by the application itself. Additional sub-directories within + src can be used as namespaces to organize source files. These directories should never + be deeper than one level. + priv - Optional. Used for application specific files. + include - Optional. Used for public include files that must be reachable from + other applications. + doc - Recommended. Any source documentation should be placed in sub-directories here. + doc/internal - Recommended. Any documentation that describes implementation details about + this application, not intended for publication, should be placed here. + doc/examples - Recommended. Source code for examples on how to use this application should + be placed here. It is encouraged that examples are sourced to the public documentation from + this directory. + doc/src - Recommended. All source files for documentation, such as Markdown, AsciiDoc or + XML-files, should be placed here. + test - Recommended. All files regarding tests, such as test suites and test specifications, + should be placed here. + + +

Other directories in the development environment may be needed. If source code from languages other + than Erlang is used, for instance C-code for NIFs, that code should be placed in a separate directory. + By convention it is recommended to prefix such directories with the language name, for example + c_src for C, java_src for Java or go_src for Go. Directories with _src + suffix indicates that it is a part of the application and the compilation step. The final build artifacts + should target the priv/lib or priv/bin directories.

+

The priv directory holds assets that the application needs during runtime. Executables should + reside in priv/bin and dynamically-linked libraries should reside in priv/lib. Other assets + are free to reside within the priv directory but it is recommended it does so in a structured manner.

+

Source files from other languages that generate Erlang code, such as ASN.1 or Mibs, should be placed + in directories, at the top level or in src, with the same name as the source language, for example + asn1 and mibs. Build artifacts should be placed in their respective language directory, + such as src for Erlang code or java_src for Java code.

+

The .app file for release may reside in the ebin-directory in a development environment + but it is encouraged that this is an artifact of the build step. By convention a .app.src file + is used, which resides in the src directory. This file is nearly identical as the + .app file but certain fields may be replaced during the build step, such as the application version.

+

Directory names should not be capitalized.

+

It is encouraged to omit empty directories.

+ +
+ +
+ + Directory Structure for a Released System +

A released application must follow a certain structure. +

+ + ─ ${application}-${version} +   ├── bin +   ├── doc + │   ├── html + │   ├── man[1-9] + │   ├── pdf + │   ├── internal + │   └── examples +   ├── ebin + │   └── ${application}.app +   ├── include +   ├── priv + │   ├── lib + │   └── bin +   └── src + + + src - Optional. Contains the Erlang source code and internal include files + used by the application itself. This directory is no longer required in a released application. + ebin - Required. Contains the Erlang object code, the beam files. + The .app file must also be placed here. + priv - Optional. Used for application specific files. code:priv_dir/1 + is to be used to access this directory. + priv/lib - Recommended. Any shared-object files that are used by the application, + such as NIFs or linked-in-drivers, should be placed here. + priv/bin - Recommended. Any executable that is used by the application, + such as port-programs, should be placed here. + include - Optional. Used for public include files that must be reachable from + other applications. + bin - Optional. Any executable that is a product of the application, + such as escripts or shell-scripts, should be placed here. + doc - Optional. Any released documentation should be placed in + sub-directories here. + doc/man1 - Recommended. Man pages for Application executables. + doc/man3 - Recommended. Man pages for module APIs. + doc/man6 - Recommended. Man pages for Application overview. + doc/html - Optional. HTML pages for the entire Application. + doc/pdf - Optional. PDF documentation for the entire Application. + + +

The src directory could be useful to release for debugging purposes but is not required. + The include directory should only be released if the applications has public include files.

+

The only documentation that is recommended to be released in this way are the man pages. HTML and PDF + will normally be distributed in some other manner.

+

It is encouraged to omit empty directories.

+
@@ -381,4 +486,3 @@ application:start(Application, Type) shutdown, not normal.

- -- cgit v1.2.3