:GLEP: XXX :Title: Live Ebuild as Template :Version: $Revision: $ :Last-Modified: $Date: $ :Author: Luca Barbato , :Status: Draft :Type: Standards Track :Content-Type: text/x-rst :Created: 12 Jun 2008 Credits ======= Thanks to Gianni Ceccarelli for the early feedback and markup help, Zack Medico for pointing some issues and suggesting solutions (and pushing me to complete it), Thomas Anderson for the help. Abstract ======== This glep provides a mechanism to allow traceable installation from live source repositories (e.g. ``svn``, ``bzr``, ``git``) using ebuilds. Motivation ========== Sometimes upstream may not provide releases often enough to satisfy certain needs, either because there isn't a release schedule or the scheduled release is too far to address certain issues or provide certain features in a timely manner. In order to provide such fixes or features the main solutions had been either backport them in form of patches or provide snapshots from the development tree if the number of changes is too high. Sometimes is needed to update the snapshots often enough that would be simpler directly using the live sources. Current situation (``-9999 ebuilds``) ----------------------------------- Right now the are some eclasses that on unpack phase fetch the sources from the upstream server, prepare them and then the usual ebuild process follows. In order to make an ebuild using those eclasses be valued as the highest possible, the simplest solution had been give it a version "high enough", commonly ``9999``. That makes simple track a single live branch per package. The same reasoning could be done with any version component in order to try to track different branches: - to track what will be the next ``1.5`` version, a version like ``1.4.9999`` or 1.5_pre9999 could be used. - to track all the improvements happening on the 1.5 branch somebody could use a version like 1.5_p9999 or 1.5.9999 again. 9999 is just an arbitrary big number. Shortcomings ------------ There are many obvious and non obvious shortcomings in this situations: - you have to hand produce "high enough" version values and be sure they do not clash (e.g. 2.3_pre9999 live ebuild being shadowed by 2.3_pre20050201 snapshot). - you cannot track what did you install since you don't have a precise information about it, emerge logs will just provide you the build date. - you cannot do exact reemerges and that may break revdep-rebuild - the package manager isn't aware of the "liveness" condition. - in order to refresh/update the installed package automatically you need either to rely on script or on sets hand produced or heuristically defined (e.g "all ebuilds that inherit eclass svn go in svn set"). - since you fetch on unpack phase you cannot use emerge --fetch consistently. This document aims to address the above shortcomings. Use Cases ========= Those are the following use case considered:: * track the tip of the main branch * track specific version branches * track multiple topic branches * Backwards Compatibility ======================= This is an expansion to [GLEP54]_. Live Template ============= Structure --------- Any numeric version component could be substituted with the keyword ``live``. The keyword must be present at most one time:: ``cat/pkg-live`` ``cat/pkg-1.live`` ``cat/pkg-1.2.live`` ``cat/pkg-1.2.3_prelive`` ``cat/pkg-1.2.2_plive`` It's advised not to chain suffixes beside ``-r`` after the live keyword even if is possible (e.g. ``cat/pkg-1.2.live_pre``) Resolution and Version Comparison --------------------------------- At resolution the live keyword is substituted with a timestamp in the form of iso date (``YYYYMMDDhhmm``) and the version comparison follows the normal version comparison rules. Generation ---------- [Details about generating a normal ebuild out of template] Informations shown on pretend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The live template is always resolved to a snapshot value, portage should mark both template and rendered templates to notify the user. live template yet to be rendered could get a specific letter "L" in order to mark it or it could be shown as is. Rendered templates will shown with the version with ``live`` replaced with the iso date and the informations about the branch and revision name will be shown on verbose in a fashion similar to what is used for useflags. Additional Phase ~~~~~~~~~~~~~~~~ [Reference about ``src_fetch`` bugXXXX_] Revision information embedding ------------------------------ In order to properly allow re-emerge, it's required that additional informations will be stored and exposed to portage. Eclass Support ~~~~~~~~~~~~~~ Live templates will use a standardized form of eclass interface to expose the revision information to the ebuild and the package manager. Every ebuild will expose the following variables: ``LIVE_URI`` ``LIVE_BRANCH`` ``LIVE_REVISION`` References ========== .. [GLEP54] scm package version suffix (http://glep.gentoo.org/glep-0054.html) .. [bugXXXX] src_fetch rfe (http://bugs.gentoo.org/XXXX) Copyright ========= This document has been placed in the public domain. .. vim: set tw=79 fileencoding=utf-8 spell spelllang=en et :