diff options
author | 2005-07-12 17:21:19 +0000 | |
---|---|---|
committer | 2020-01-09 23:50:51 +0100 | |
commit | b5eb706b0d006535cb8e48b7a03177249a630dd0 (patch) | |
tree | bd1ad55b9d89bbe5b185210eb838759e4aa4923e /general-concepts/use-flags | |
download | devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.tar.gz devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.tar.bz2 devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.zip |
reStructuredText source of the devmanual
Taken from ~sekretarz/public_html/devmanual.tar.bz on dev.gentoo.org
and removed all generated HTML, PNG, and temporary files.
Timestamp of oldest file: 2005-06-04 11:50:45 +0000
Timestamp of newest file: 2005-07-12 17:21:19 +0000
Signed-off-by: Ulrich Müller <ulm@gentoo.org>
Diffstat (limited to 'general-concepts/use-flags')
-rw-r--r-- | general-concepts/use-flags/conflicting-flags.ebuild | 20 | ||||
-rw-r--r-- | general-concepts/use-flags/noblah-1.ebuild | 3 | ||||
-rw-r--r-- | general-concepts/use-flags/noblah-2.ebuild | 3 | ||||
-rw-r--r-- | general-concepts/use-flags/noblah-3.ebuild | 3 | ||||
-rw-r--r-- | general-concepts/use-flags/noblah-4.ebuild | 3 | ||||
-rw-r--r-- | general-concepts/use-flags/text.rst | 130 |
6 files changed, 162 insertions, 0 deletions
diff --git a/general-concepts/use-flags/conflicting-flags.ebuild b/general-concepts/use-flags/conflicting-flags.ebuild new file mode 100644 index 0000000..29b9905 --- /dev/null +++ b/general-concepts/use-flags/conflicting-flags.ebuild @@ -0,0 +1,20 @@ +# Header + +src_compile() { + local myconf + + if use ssl && use gnutls ; then + myconf="${myconf} --enable-ssl --with-ssl=gnutls" + elif use ssl && ! use gnutls ; then + myconf="${myconf} --enable-ssl --with-ssl=openssl" + else + myconf="${myconf} --disable-ssl" + fi + + econf \ + # Other stuff + ${myconf} \ + || die "configure failed + + emake || die "make failed" +} diff --git a/general-concepts/use-flags/noblah-1.ebuild b/general-concepts/use-flags/noblah-1.ebuild new file mode 100644 index 0000000..07618e4 --- /dev/null +++ b/general-concepts/use-flags/noblah-1.ebuild @@ -0,0 +1,3 @@ +# Header + +RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )" diff --git a/general-concepts/use-flags/noblah-2.ebuild b/general-concepts/use-flags/noblah-2.ebuild new file mode 100644 index 0000000..b653ce5 --- /dev/null +++ b/general-concepts/use-flags/noblah-2.ebuild @@ -0,0 +1,3 @@ +# Header + +DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )" diff --git a/general-concepts/use-flags/noblah-3.ebuild b/general-concepts/use-flags/noblah-3.ebuild new file mode 100644 index 0000000..bbcaefa --- /dev/null +++ b/general-concepts/use-flags/noblah-3.ebuild @@ -0,0 +1,3 @@ +# Header + +RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )" diff --git a/general-concepts/use-flags/noblah-4.ebuild b/general-concepts/use-flags/noblah-4.ebuild new file mode 100644 index 0000000..5676176 --- /dev/null +++ b/general-concepts/use-flags/noblah-4.ebuild @@ -0,0 +1,3 @@ +# Header + +RDEPEND="!noalsa? ( media-libs/alsa )" diff --git a/general-concepts/use-flags/text.rst b/general-concepts/use-flags/text.rst new file mode 100644 index 0000000..98f205c --- /dev/null +++ b/general-concepts/use-flags/text.rst @@ -0,0 +1,130 @@ +USE Flags +========= + +USE flags are to control *optional* dependencies and settings which the user may +reasonably want to select. For example, ``vim`` can optionally build with +support for the ``ruby`` interpreter, and it needs ``ruby`` installed to do this +-- we use the ``ruby`` USE flag to provide this option. On the other hand, +``glark`` requires ``ruby`` no matter what, so no USE flag is used here. + +No combination of USE flags should cause a package to fail to build. + +Packages should not configure and link based upon what is available at compile +time -- any autodetection must be overridden. + +``noblah`` USE Flags +-------------------- + +If at all possible, avoid ``noblah`` style USE flags. These break ``use.mask`` +and cause all sorts of complications for arch developers. Here's why: + +Consider a hypothetical package named 'vplayer', which plays videos. This +package has optional support, via USE flags, for various sound and video output +methods, various video codecs and so on. + +One of vplayer's optional features is support for the 'fakemedia' codec, which +is unfortunately only available as a dodgy x86 binary. We *could* handle this by +doing something like: + +.. CODESAMPLE noblah-1.ebuild + +Except this is pretty nasty -- what happens when an amd64 binary is made as +well? Also, users on other archs will see fakemedia listed in ``emerge -pv`` +output, even though it is not actually available. + +Similarly, say vplayer supports output via the ALSA codec as one option. +However, ALSA isn't (or wasn't when this example was written) available on sparc +or alpha. So we could do: + +.. CODESAMPLE noblah-2.ebuild + +Again, it's messy, and alsa still shows up in the ``emerge -pv`` output. Also, +once ALSA starts working on sparc, every ebuild that does this would have to be +manually edited. + +The solution is ``use.mask``, which is documented in `Profiles use.mask File`_. +Each profile can have a ``use.mask`` file which can be used to forcibly disable +certain USE flags on a given arch (or subarch, or subprofile). So, if the +``fakemedia`` USE flag was use.masked on every non-x86 profile, the following +would be totally legal and wouldn't break anything: + +.. CODESAMPLE noblah-3.ebuild + +Users of non-x86 would see the following when doing ``emerge -pv vplayer``: :: + + [ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz + +To get a flag added to ``use.mask``, ask the relevant arch team. + +So what's the problem with ``noblah`` flags? + +There's no way to forcibly *enable* a given USE flag on a particular profile. +So, something like: + +.. CODESAMPLE noblah-4.ebuild + +will make your package unusable by archs without ALSA support, and there is no +way to fix it that doesn't involve adding in nasty ``arch?`` flags. + +Local and Global USE Flags +-------------------------- + +USE flags are categorised as either local or global. A global USE flag must +satisfy several criteria: + + * It is used by many different packages. + * It has a general non-specific purpose. + +The second point is important. If the effect of the ``thing`` USE flag upon +``pkg-one`` is substantially different from the effect it has upon ``pkg-two``, +then ``thing`` is not a suitable candidate for being made a global flag. In +particular, note that if ``client`` and ``server`` USE flags are ever +introduced, they can not be global USE flags for this reason. + +Before introducing a new global USE flag, it must be discussed on the gentoo-dev +mailing list. + +USE Flag Descriptions +--------------------- + +All USE flags (excluding ``USE_EXPAND`` flags) must be described in either +``use.desc`` or ``use.local.desc`` in the ``profiles/`` directory. See +`portage-5`_ or the comments in these files for an explanation of the format. +Remember to keep these files sorted. + +Conflicting USE Flags +--------------------- + +Occasionally, ebuilds will have conflicting USE flags for functionality. +Checking for them and returning an error is *not* a viable solution. Instead, +you must pick one of the USE flags in conflict to favour. + +One example comes from the ``msmtp`` ebuilds. The package can use either SSL +with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS is more +featureful than OpenSSL, it is favoured: + +.. CODESAMPLE conflicting-flags.ebuild + +USE_EXPAND and ARCH USE Flags +----------------------------- + +The ``VIDEO_CARDS``, ``INPUT_DEVICES`` and ``LINGUAS`` variables are +automatically expanded into USE flags. These are known as ``USE_EXPAND`` +variables. If the user has ``LINGUAS="en fr"`` in ``make.conf``, for example, +then ``USE="linguas_en linguas_fr"`` will automatically be set by portage. + +The ``USE_EXPAND`` list is set in ``profiles/base/make.defaults`` as of Portage +2.0.51.20. This must not be modified without discussion on the gentoo-dev list, +and it must not be modified in any subprofile. + +The current architecture (eg ``x86``, ``sparc``, ``ppc-macos``) will +automatically be set as a USE flag as well. See ``profiles/arch.list`` for a +full list of valid architecture keywords, and `GLEP 22`_ for an explanation of +the format. + +.. Warning:: It is a common misconception that the architecture variable is somehow + related to ``ACCEPT_KEYWORDS``. It isn't. Accepting ``x86`` keywords on + ``sparc``, for example, won't set ``USE="x86"``. Similarly, there are no + ``~arch`` USE flags, so don't try ``if use ~x86``. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. |