[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/functions/

["Markos Chandras" <hwoarang@gentoo.org>]

commit:     2a7d19973f0713e66b38b7af04a263ae248fe7ca
Author:     W. Trevor King <wking <AT> tremily <DOT> us>
AuthorDate: Wed Sep  3 01:15:44 2014 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Wed Sep  3 15:51:03 2014 +0000
URL:        http://sources.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=2a7d1997

ebuild-writing/functions: Don't allow network access

There have been a number of bugs filed to remove network access from
ebuild phases [1,2,...], but until now this policy was undocumented
here.  We'll have to relax this restriction if the src_fetch [3,4,5] or
pkg_fetch [6] proposals being discussed for EAPI-6 are accepted, but
neither is currently mentioned in either the PMS [7] or Portage [8].

Portage *does* have a network-sandbox feature [9,10], which applies to
all src_* phases except src_unpack (for live ebuilds).  I think it
should be applied to pkg_* phases too, but Michał thinks they may need
networking "for some kind of IPC" [11].  Alexis pointed out that a
strict network-sandbox will break distcc [12], but since that network
access is the result of enabling a Portage feature (and not initiated
by the ebuild or package itself), it falls outside the scope of this
policy.

[1]: https://bugs.gentoo.org/show_bug.cgi?id=315403
     Summary: media-video/jubler fails to build without network
[2]: https://bugs.gentoo.org/show_bug.cgi?id=336771
     Summary: dev-libs/libevent tests require network access
[3]: https://bugs.gentoo.org/show_bug.cgi?id=182028
     Summary: [Future EAPI] About managing CVS/SUBVERSION version of
       software
[4]: http://thread.gmane.org/gmane.linux.gentoo.devel/47645/focus=52918
     From: Marijn Schouten <hkBst <AT> gentoo.org>
     Subject: src_fetch (was Re: EAPI 1 (Was: Re: Monthly Gentoo
       Council Reminder for April))
     Date: 2007-11-09 17:41:38 GMT
[5]: http://thread.gmane.org/gmane.linux.gentoo.devel/87869
     From: Michał Górny <mgorny <AT> gentoo.org>
     Subject: [EAPI 6] src_fetch() for fetching live sources
     Date: 2013-08-27 10:01:27 GMT
[6]: http://thread.gmane.org/gmane.linux.gentoo.devel/87869/focus=878773
     From: Ian Stakenvicius <axs <AT> gentoo.org>
     Subject: Re: [EAPI 6] src_fetch() for fetching live sources
     Date: 2013-08-27 14:33:27 GMT
[7]: git://git.overlays.gentoo.org/proj/pms.git
[8]: git://git.overlays.gentoo.org/proj/portage.git
[9]: http://thread.gmane.org/gmane.linux.gentoo.devel/87641
     From: Michał Górny <mgorny <AT> gentoo.org>
     Subject: New developer features in portage: cgroup,
       network-sandbox, ipc-sandbox
     Date: 2013-08-20 10:26:03 GMT
[10]: http://thread.gmane.org/gmane.linux.gentoo.devel/91131
      From: Michał Górny <mgorny <AT> gentoo.org>
      Subject: RFC: enabling ipc-sandbox & network-sandbox by default
      Date: 2014-05-11 21:42:38 GMT
[11]: http://article.gmane.org/gmane.linux.gentoo.devel/87641
      From: Michał Górny <mgorny <AT> gentoo.org>
      Subject: New developer features in portage: cgroup,
        network-sandbox, ipc-sandbox
      Date: 2013-08-20 10:26:03 GMT
[12]: http://thread.gmane.org/gmane.linux.gentoo.devel/87641/focus=87658
      From: Alexis Ballier <aballier <AT> gentoo.org>
      Subject: Re: New developer features in portage: cgroup,
        network-sandbox, ipc-sandbox
      Date: 2013-08-20 15:04:35 GMT

---
 ebuild-writing/functions/text.xml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml
index 09a910e..d10a51f 100644
--- a/ebuild-writing/functions/text.xml
+++ b/ebuild-writing/functions/text.xml
@@ -35,6 +35,19 @@ When testing or debugging, you can instruct Portage to execute a specific functi
 from an ebuild by using the <c>ebuild</c> command, see the <c>ebuild(1)</c> manual
 page for further information.
 </p>
+
+<p>
+Downloading a package's source happens before any of these phases, so
+<c>emerge --fetchonly</c> should perform all the network access you
+need (unless you're using live ebuilds).  Network access outside of
+this would not be cached locally (e.g. in <c>${DISTDIR}</c>, see
+<uri link="::ebuild-writing/variables#Predefined Read-Only Variables."/>),
+which makes it hard to have reproducible builds (see
+<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>).
+Avoid network access in any phase by using local files, extending
+<c>SRC_URI</c> (see
+<uri link="::ebuild-writing/variables#Ebuild-defined Variables"/>), etc.
+</p>
 </body>
 
 <section>