From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id EAD62138200 for ; Wed, 12 Jun 2013 21:10:55 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 6CEE8E08C0; Wed, 12 Jun 2013 21:10:52 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id D364EE08D1 for ; Wed, 12 Jun 2013 21:10:51 +0000 (UTC) Received: from hornbill.gentoo.org (hornbill.gentoo.org [94.100.119.163]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 7484333E3D5 for ; Wed, 12 Jun 2013 21:10:50 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by hornbill.gentoo.org (Postfix) with ESMTP id EFAD9E545F for ; Wed, 12 Jun 2013 21:10:48 +0000 (UTC) From: "André Erdmann" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "André Erdmann" Message-ID: <1371071343.b882ecc22d31458fc64949fd458931ec79a88456.dywi@gentoo> Subject: [gentoo-commits] proj/R_overlay:gsoc13/next commit in: doc/rst/ X-VCS-Repository: proj/R_overlay X-VCS-Files: doc/rst/usage.rst X-VCS-Directories: doc/rst/ X-VCS-Committer: dywi X-VCS-Committer-Name: André Erdmann X-VCS-Revision: b882ecc22d31458fc64949fd458931ec79a88456 X-VCS-Branch: gsoc13/next Date: Wed, 12 Jun 2013 21:10:48 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: c10b6fbe-bb6b-49f8-b626-eb9b7766ea43 X-Archives-Hash: 745d524a816da5424565e66b350727c7 commit: b882ecc22d31458fc64949fd458931ec79a88456 Author: André Erdmann mailerd de> AuthorDate: Wed Jun 12 21:09:03 2013 +0000 Commit: André Erdmann mailerd de> CommitDate: Wed Jun 12 21:09:03 2013 +0000 URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=b882ecc2 doc/rst: additions dir --- doc/rst/usage.rst | 132 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 120 insertions(+), 12 deletions(-) diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst index adf26da..ab2c563 100644 --- a/doc/rst/usage.rst +++ b/doc/rst/usage.rst @@ -52,19 +52,20 @@ This document is targeted at * *roverlay* maintainers who **control and test overlay creation**, e.g. configure which R packages will be part of the generated overlay - Depending on what you want to configure, chapters 5-8 are relevant, - namely `Repositories / Getting Packages`_, `Dependency Rules`_, - `Configuration Reference`_ and `Field Definition Config`_. + Depending on what you want to configure, chapters 5-10 are relevant, + namely `Repositories / Getting Packages`_, `Additions Directory`, + `Dependency Rules`_, `Package Rules`_, `Configuration Reference`_ + and `Field Definition Config`_. There is another chapter that is only interesting for testing, the - `Dependency Resolution Console`_ (10), which can be used to interactively + `Dependency Resolution Console`_ (11), which can be used to interactively test dependency rules. * *roverlay* code maintainers who want to know **how roverlay works** for code improvements etc. - The most important chapter is `Implementation Overview`_ (11) which has - references to other chapters (4-9) where required. + The most important chapter is `Implementation Overview`_ (12) which has + references to other chapters (4-10) where required. Expected prior knowlegde: @@ -279,13 +280,19 @@ have reasonable defaults if *roverlay* has been installed using *emerge*: Example: REPO_CONFIG = ~/roverlay/config/repo.list - PACKAGE_RULES: + PACKAGE_RULES A list of files and/or directories with package rules. Package rules can be used to control overlay/ebuild creation. This option is not required. Example: PACKAGE_RULES = ~/roverlay/config/packagerules.d + ADDITIONS_DIR + Directory with an overlay-like structure that contains extra files, e.g. + ebuild patches and hand-written ebuilds. + + Example: ADDITIONS_DIR = ~/roverlay/additions + FIELD_DEFINITION The value of this option should point to a field definition file which controls how an R package's DESCRIPTION file is read. @@ -330,6 +337,7 @@ There is another option that is useful for creating new dependency rules, LOG_FILE_UNRESOLVABLE_, which will write all unresolvable dependencies to the specified file (one dependency string per line). + +++++++++++++++++++++++++++++++++++++++++++++++++ Extended Configuration / Where to go from here? +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -510,7 +518,9 @@ These are the steps that *roverlay* performs: 2. scan the R Overlay directory (if it exists) for valid ebuilds -3. **add** - queue all R packages for ebuild creation +3. import ebuilds from the additions dir + +4. **add** - queue all R packages for ebuild creation * all repositories are asked to list their packages which are then added to a queue @@ -522,7 +532,7 @@ These are the steps that *roverlay* performs: See also: `Package Rules`_ -4. **create** - process each package *p* from the package queue +5. **create** - process each package *p* from the package queue (thread-able on a per package basis) * read *p*'s DESCRIPTION file that contains information fields @@ -545,9 +555,9 @@ These are the steps that *roverlay* performs: * **done** with *p* - the overlay creator takes control over *p* and may decide to write *p*'s ebuild now (or later) -5. write the overlay +6. write the overlay - * write all ebuilds + * write all ebuilds and apply patches to them (supports threads on a per package basis) * write the *metadata.xml* files @@ -957,6 +967,91 @@ A local directory will never be modified. websync_pkglist_. +===================== + Additions Directory +===================== + +The *additions directory* is a directory with overlay-like structure that +contains extra files for overlay creation. Currently, ebuild patches and +ebuild files are supported. + +To give an idea of how this directory could + + + +------------------ + Patching ebuilds +------------------ + +Patches can apply to a **specific version** or to **all versions** of a +package. + +The naming convention for patches is (full filesystem paths relative to the +additions dir): + +.. code:: text + + # version-specific patches + ${CATEGORY}/${PN}/${PF}[-dddd].patch + + # version-agnostic patches + ${CATEGORY}/${PN}/${PN}[-dddd].patch + + +The *-dddd* part is optional and can be used to apply more than one patch to +an ebuild in the specified order. *d* should be a digit (0..9) and exactly +4 digits are expected. The not-numbered patch is always applied first. +So, in theory, up to 10001 patches per ebuild are supported. + +The *default* (version-agnostic) patches are only applied to ebuilds for +which no version-specific patches exist. + +Exempting a specific ebuild from being patched can be achieved by creating +an empty patch file (or a symlink to /dev/null). This is only necessary +if *default* patches are available, else it adds some overhead. + +.. Caution:: + + Don't try to patch the (R)DEPEND variables of an ebuild. + It will *randomly* break because *roverlay* uses unordered data structures + for collecting dependencies. + +Example: + +.. code:: text + + /sci-CRAN/R_oo/R_oo-1.9.8.patch + /sci-CRAN/R_oo/R_oo-1.9.8-0000.patch + /sci-CRAN/R_oo/R_oo-1.9.8-0001.patch + /sci-R/seewave/seewave-1.6.7.patch + /sci-R/seewave/seewave.patch + + +------------------- + Importing ebuilds +------------------- + +Foreign ebuilds can be imported into the overlay by simple putting them into +the additions directory. + +The naming convention is similar to ebuild patches and identical to the +portage tree: + +.. code:: + + ${CATEGORY}/${PN}/${PF}.ebuild + + +Ebuilds imported that way can not be overwritten by generated ebuilds and +benefit from most overlay creation features, e.g. Manifest file creation. +However, they cannot be used for metadata creation. + +.. Important:: + + Importing ebuilds is only supported by the default Manifest implementation + (*ebuildmanifest*). + + ================== Dependency Rules ================== @@ -1747,6 +1842,11 @@ RSYNC_BWLIMIT overlay options ----------------- +.. _ADDITIONS_DIR: + +ADDITIONS_DIR: + Alias to OVERLAY_ADDITIONS_DIR_. + .. _DISTDIR: DISTDIR @@ -1772,6 +1872,14 @@ ECLASS MANIFEST_IMPLEMENTATION Alias to OVERLAY_MANIFEST_IMPLEMENTATION_. +.. _OVERLAY_ADDITIONS_DIR: + +OVERLAY_ADDITIONS_DIR + Directory with an overlay-like structure that contains extra files, e.g. + ebuild patches and hand-written ebuilds. This option is not required. + + Defaults to , which disables this feature. + .. _OVERLAY_CATEGORY: OVERLAY_CATEGORY @@ -1790,7 +1898,7 @@ OVERLAY_DIR .. _OVERLAY_DISTDIR_FLAT: OVERLAY_DISTDIR_FLAT - A *bool* that controls the overall layout of _OVERLAY_DISTDIR_ROOT. + A *bool* that controls the overall layout of OVERLAY_DISTDIR_ROOT_. A flat distdir is a single directory with all package files or package file links in it. A nested distdir contains per-package directories. From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id 69F341381F3 for ; Thu, 13 Jun 2013 16:34:42 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 1D822E09B8; Thu, 13 Jun 2013 16:34:36 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 95394E09B8 for ; Thu, 13 Jun 2013 16:34:35 +0000 (UTC) Received: from hornbill.gentoo.org (hornbill.gentoo.org [94.100.119.163]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id E207733E4C6 for ; Thu, 13 Jun 2013 16:34:32 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by hornbill.gentoo.org (Postfix) with ESMTP id 101E3E547F for ; Thu, 13 Jun 2013 16:34:31 +0000 (UTC) From: "André Erdmann" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "André Erdmann" Message-ID: <1371071343.b882ecc22d31458fc64949fd458931ec79a88456.dywi@gentoo> Subject: [gentoo-commits] proj/R_overlay:master commit in: doc/rst/ X-VCS-Repository: proj/R_overlay X-VCS-Files: doc/rst/usage.rst X-VCS-Directories: doc/rst/ X-VCS-Committer: dywi X-VCS-Committer-Name: André Erdmann X-VCS-Revision: b882ecc22d31458fc64949fd458931ec79a88456 X-VCS-Branch: master Date: Thu, 13 Jun 2013 16:34:31 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: 9677d4a1-718f-48c3-ad35-98971254ed77 X-Archives-Hash: c8378d40e14e807e1565a76b4f453d67 Message-ID: <20130613163431.7yzo2Q6qSQ1flcbC_5Gk8LxxX38ypqwvJwEnwKgI7XU@z> commit: b882ecc22d31458fc64949fd458931ec79a88456 Author: André Erdmann mailerd de> AuthorDate: Wed Jun 12 21:09:03 2013 +0000 Commit: André Erdmann mailerd de> CommitDate: Wed Jun 12 21:09:03 2013 +0000 URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=b882ecc2 doc/rst: additions dir --- doc/rst/usage.rst | 132 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 120 insertions(+), 12 deletions(-) diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst index adf26da..ab2c563 100644 --- a/doc/rst/usage.rst +++ b/doc/rst/usage.rst @@ -52,19 +52,20 @@ This document is targeted at * *roverlay* maintainers who **control and test overlay creation**, e.g. configure which R packages will be part of the generated overlay - Depending on what you want to configure, chapters 5-8 are relevant, - namely `Repositories / Getting Packages`_, `Dependency Rules`_, - `Configuration Reference`_ and `Field Definition Config`_. + Depending on what you want to configure, chapters 5-10 are relevant, + namely `Repositories / Getting Packages`_, `Additions Directory`, + `Dependency Rules`_, `Package Rules`_, `Configuration Reference`_ + and `Field Definition Config`_. There is another chapter that is only interesting for testing, the - `Dependency Resolution Console`_ (10), which can be used to interactively + `Dependency Resolution Console`_ (11), which can be used to interactively test dependency rules. * *roverlay* code maintainers who want to know **how roverlay works** for code improvements etc. - The most important chapter is `Implementation Overview`_ (11) which has - references to other chapters (4-9) where required. + The most important chapter is `Implementation Overview`_ (12) which has + references to other chapters (4-10) where required. Expected prior knowlegde: @@ -279,13 +280,19 @@ have reasonable defaults if *roverlay* has been installed using *emerge*: Example: REPO_CONFIG = ~/roverlay/config/repo.list - PACKAGE_RULES: + PACKAGE_RULES A list of files and/or directories with package rules. Package rules can be used to control overlay/ebuild creation. This option is not required. Example: PACKAGE_RULES = ~/roverlay/config/packagerules.d + ADDITIONS_DIR + Directory with an overlay-like structure that contains extra files, e.g. + ebuild patches and hand-written ebuilds. + + Example: ADDITIONS_DIR = ~/roverlay/additions + FIELD_DEFINITION The value of this option should point to a field definition file which controls how an R package's DESCRIPTION file is read. @@ -330,6 +337,7 @@ There is another option that is useful for creating new dependency rules, LOG_FILE_UNRESOLVABLE_, which will write all unresolvable dependencies to the specified file (one dependency string per line). + +++++++++++++++++++++++++++++++++++++++++++++++++ Extended Configuration / Where to go from here? +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -510,7 +518,9 @@ These are the steps that *roverlay* performs: 2. scan the R Overlay directory (if it exists) for valid ebuilds -3. **add** - queue all R packages for ebuild creation +3. import ebuilds from the additions dir + +4. **add** - queue all R packages for ebuild creation * all repositories are asked to list their packages which are then added to a queue @@ -522,7 +532,7 @@ These are the steps that *roverlay* performs: See also: `Package Rules`_ -4. **create** - process each package *p* from the package queue +5. **create** - process each package *p* from the package queue (thread-able on a per package basis) * read *p*'s DESCRIPTION file that contains information fields @@ -545,9 +555,9 @@ These are the steps that *roverlay* performs: * **done** with *p* - the overlay creator takes control over *p* and may decide to write *p*'s ebuild now (or later) -5. write the overlay +6. write the overlay - * write all ebuilds + * write all ebuilds and apply patches to them (supports threads on a per package basis) * write the *metadata.xml* files @@ -957,6 +967,91 @@ A local directory will never be modified. websync_pkglist_. +===================== + Additions Directory +===================== + +The *additions directory* is a directory with overlay-like structure that +contains extra files for overlay creation. Currently, ebuild patches and +ebuild files are supported. + +To give an idea of how this directory could + + + +------------------ + Patching ebuilds +------------------ + +Patches can apply to a **specific version** or to **all versions** of a +package. + +The naming convention for patches is (full filesystem paths relative to the +additions dir): + +.. code:: text + + # version-specific patches + ${CATEGORY}/${PN}/${PF}[-dddd].patch + + # version-agnostic patches + ${CATEGORY}/${PN}/${PN}[-dddd].patch + + +The *-dddd* part is optional and can be used to apply more than one patch to +an ebuild in the specified order. *d* should be a digit (0..9) and exactly +4 digits are expected. The not-numbered patch is always applied first. +So, in theory, up to 10001 patches per ebuild are supported. + +The *default* (version-agnostic) patches are only applied to ebuilds for +which no version-specific patches exist. + +Exempting a specific ebuild from being patched can be achieved by creating +an empty patch file (or a symlink to /dev/null). This is only necessary +if *default* patches are available, else it adds some overhead. + +.. Caution:: + + Don't try to patch the (R)DEPEND variables of an ebuild. + It will *randomly* break because *roverlay* uses unordered data structures + for collecting dependencies. + +Example: + +.. code:: text + + /sci-CRAN/R_oo/R_oo-1.9.8.patch + /sci-CRAN/R_oo/R_oo-1.9.8-0000.patch + /sci-CRAN/R_oo/R_oo-1.9.8-0001.patch + /sci-R/seewave/seewave-1.6.7.patch + /sci-R/seewave/seewave.patch + + +------------------- + Importing ebuilds +------------------- + +Foreign ebuilds can be imported into the overlay by simple putting them into +the additions directory. + +The naming convention is similar to ebuild patches and identical to the +portage tree: + +.. code:: + + ${CATEGORY}/${PN}/${PF}.ebuild + + +Ebuilds imported that way can not be overwritten by generated ebuilds and +benefit from most overlay creation features, e.g. Manifest file creation. +However, they cannot be used for metadata creation. + +.. Important:: + + Importing ebuilds is only supported by the default Manifest implementation + (*ebuildmanifest*). + + ================== Dependency Rules ================== @@ -1747,6 +1842,11 @@ RSYNC_BWLIMIT overlay options ----------------- +.. _ADDITIONS_DIR: + +ADDITIONS_DIR: + Alias to OVERLAY_ADDITIONS_DIR_. + .. _DISTDIR: DISTDIR @@ -1772,6 +1872,14 @@ ECLASS MANIFEST_IMPLEMENTATION Alias to OVERLAY_MANIFEST_IMPLEMENTATION_. +.. _OVERLAY_ADDITIONS_DIR: + +OVERLAY_ADDITIONS_DIR + Directory with an overlay-like structure that contains extra files, e.g. + ebuild patches and hand-written ebuilds. This option is not required. + + Defaults to , which disables this feature. + .. _OVERLAY_CATEGORY: OVERLAY_CATEGORY @@ -1790,7 +1898,7 @@ OVERLAY_DIR .. _OVERLAY_DISTDIR_FLAT: OVERLAY_DISTDIR_FLAT - A *bool* that controls the overall layout of _OVERLAY_DISTDIR_ROOT. + A *bool* that controls the overall layout of OVERLAY_DISTDIR_ROOT_. A flat distdir is a single directory with all package files or package file links in it. A nested distdir contains per-package directories.