[commits] [Wiki] changed: Doc/Dev/HordeYmlFormat

[Ralf Lang (B1 Systems GmbH)]

rlang  Sun, 24 Nov 2019 09:48:06 +0000

Modified page: https://wiki.horde.org/Doc/Dev/HordeYmlFormat
New Revision:  2
Change log:  add code examples

@@ -6,55 +6,141 @@

  Document .horde.yml format and how it relates to composer json and pear xml

  TODO: beautify
+
+++ Meta data head

  id: string, mandatory, uppercase and minus Horde_ for libs,  
lowercase for apps (horde, turba, Autoloader, Exception)
  name: string, mandatory, Uppercase (Horde, Turba, Autoloader, Exception)
  full: string, mandatory, a one-line description
  description: string, mandatory, a multi-line description
  list: string, mandatory, may be empty: a hint on the mailing list  
appropriate for the component
-type: string, mandatory, either "application" or "library"
+type: string, mandatory, classic: either "application" or "library",  
modern: horde-application, horde-library, horde-theme
  homepage: string, mandatory, a related informational url
  authors: list, each element has string attributes name, user, email,  
active (true/false), role (lead, developer)
  version: has sub keys api and release each with a version string  
(1.0.0 format)
  state: has sub keys api and release, each with a stabilitiy string  
(stable, beta, alpha)
  license: has subkeys identifier and uri
  license: identifier: An SPDX license identifier string
  license: uri: a link to a fulltext license
+
+Example:
+<code>
+---
+id: Db
+name: Db
+full: Database abstraction library
+description: Database access and SQL abstraction layer.
+list: dev
+type: library
+homepage: https://www.horde.org/libraries/Horde_Db
+authors:
+  -
+    name: Jan Schneider
+    user: jan
+    email: jan at horde.org
+    active: true
+    role: lead
+  -
+    name: Mike Naberezny
+    user: mnaberez
+    email: mike at naberezny.com
+    active: false
+    role: lead
+  -
+    name: Chuck Hagenbuch
+    user: chuck
+    email: chuck at horde.org
+    active: false
+    role: lead
+version:
+  release: 2.4.1
+  api: 2.4.0
+state:
+  release: stable
+  api: stable
+license:
+  identifier: BSD-2-Clause
+  uri: http://www.horde.org/licenses/bsd
+</code>
+
+++ PHP and Pear Dependencies
+
+This covers PHP itself, php binary modules and PEAR dependencies both  
inside horde and external
+
  dependencies: top level structure for several optional keys
  dependencies: required: multilevel list of mandatory dependencies  
(php, pear, ext) - The key and all sub keys are optional
  dependencies: required: php: optional key. The value should be a  
version constraint string
  dependencies: required: pear: optional key. This is a list of  
channel/package keys and version constraint values. For pecl  
extensions, there may be additional sub keys instead of a version string
  dependencies: required: ext: optional key. This is a list of php  
binary extensions (hash, pdo, ...) as keys and version constraint  
strings as values.
  dependencies: optional: multilevel list of optional, suggested  
collaborators (pear, ext) - The key and all sub keys are optional
  dependencies: required: pear: optional key. This is a list of  
channel/package keys and version constraint values. For pecl  
extensions, there may be
-Suggested additions to the format
-
-++ Additions for transitioning to composer
-
+
+<code>
+dependencies:
+  required:
+    php: ^5.3 || ^7
+    pear:
+      pear.horde.org/Horde_Date: ^2
+      pear.horde.org/Horde_Exception: ^2
+      pear.horde.org/Horde_Support: ^2
+      pear.horde.org/Horde_Util: ^2
+  optional:
+    pear:
+      pear.horde.org/Horde_Autoloader: ^2
+      pear.horde.org/Horde_Cache: ^2
+      pear.horde.org/Horde_Log: ^2
+      pear.horde.org/Horde_Test: ^2.1
+    ext:
+      mysql: '*'
+      mysqli: '*'
+      oci8: '*'
+      PDO: '*'
+</ccode>
+
+++ Additions for transitioning to composer based installs
+
  optional top level key "autoload", inspired by corresponding  
composer.yml structure
  It hints how autoloaders should expect to find php classes from the package.

  Structure:
  autoload: psr-0: list of "Class_Prefix" : "dir"
  autoload: psr-4: list of "\\Prefix" : "dir"
+
+
  autoload: classmap: list of directories to recursively scan for php  
files containing classes
+
+<code>
+autoload:
+  classmap: ['lib/']
+</code>

  The default if absent would be equivalent to psr-0: "Horde_Foo": /Lib

-+++ Composer native definitions
++++ Composer native dependency definitions

  Example:  
https://github.com/maintaina-com/Dav/commit/71dd9714a8d49c28b5cfe1b0bcd089eb6fa93226
  components version:  
https://github.com/maintaina-com/components/commit/3ffe6013081287bb02260e2d55291f98b93f6e15

  It is now possible in horde.yml to define dependencies for the  
composer.json file which are not derived from pear dependencies.
  This allows unbundling composer libraries like sabre dav from  
wrapping horde libraries like horde/dav.
  New libraries which do not intend to support pear installations at  
all could easily just define their dependencies here

+<code>
+dependencies:
+  required:
+    php: ^5.4.1 || ^7
+    composer:
+        sabre/dav: ~2.0.0
+</code>

  +++ Composer vendor-bin

  By default, the composer.json writer will treat all executable files  
living directly under package/bin as vendor binaries.
  This can be overridden:
  commands: optional: List of paths relative to package root which  
should be offered as vendor binaries. If you provide commands, no  
automatic search in bin/ will happen.
  nocommands: optional: List of paths relative to package root which  
should not be offered as vendor binaries. nocommands wins over  
commands list or implicitly found bin/
+<code>
+nocommands:
+  - 'bin/horde-bootstrap'
+<code>