/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-variables.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-working-variables.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.23 - (hide annotations) (download) (as text)
Fri Jun 29 15:41:54 2012 UTC (2 years, 2 months ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.22: +13 -5 lines
File MIME type: application/xml
Fix bug #414801 - Add blurb about COLON_SEPARATED and SPACE_SEPARATED. Thanks to "lynx" for reporting and suggesting the fix

1 swift 1.5 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4 swift 1.1 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 neysx 1.17 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.1
7 swift 1.23 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-variables.xml,v 1.22 2007/05/19 04:13:46 nightmorph Exp $ -->
8 swift 1.1
9     <sections>
10 swift 1.9
11 neysx 1.20 <abstract>
12     With Gentoo you can easily manage the environment variables for your system.
13     This chapter explains how you do that, and also describes frequently used
14     variables.
15     </abstract>
16    
17 swift 1.23 <version>2</version>
18     <date>2012-06-29</date>
19 swift 1.9
20 swift 1.1 <section>
21     <title>Environment Variables?</title>
22     <subsection>
23     <title>What they are</title>
24     <body>
25    
26 swift 1.2 <p>
27     An environment variable is a named object that contains information used by one
28 neysx 1.8 or more applications. Many users (and especially those new to Linux) find this
29     a bit weird or unmanageable. However, this is a mistake: by using environment
30     variables one can easily change a configuration setting for one or more
31     applications.
32 swift 1.2 </p>
33 swift 1.1
34     </body>
35     </subsection>
36     <subsection>
37     <title>Important Examples</title>
38     <body>
39    
40 swift 1.2 <p>
41     The following table lists a number of variables used by a Linux system and
42     describes their use. Example values are presented after the table.
43     </p>
44    
45     <table>
46     <tr>
47     <th>Variable</th>
48     <th>Description</th>
49     </tr>
50     <tr>
51     <ti>PATH</ti>
52     <ti>
53     This variable contains a colon-separated list of directories in which your
54     system looks for executable files. If you enter a name of an executable
55     (such as <c>ls</c>, <c>rc-update</c> or <c>emerge</c>) but this executable
56     is not located in a listed directory, your system will not execute it
57     (unless you enter the full path as command, such as <c>/bin/ls</c>).
58     </ti>
59     </tr>
60     <tr>
61     <ti>ROOTPATH</ti>
62     <ti>
63     This variable has the same function as <c>PATH</c>, but this one only lists
64     the directories that should be checked when the root-user enters a command.
65     </ti>
66     </tr>
67     <tr>
68     <ti>LDPATH</ti>
69     <ti>
70     This variable contains a colon-separated list of directories in which the
71     dynamical linker searches through to find a library.
72     </ti>
73     </tr>
74     <tr>
75     <ti>MANPATH</ti>
76     <ti>
77     This variable contains a colon-separated list of directories in which the
78     <c>man</c> command searches for the man pages.
79     </ti>
80     </tr>
81     <tr>
82     <ti>INFODIR</ti>
83     <ti>
84     This variable contains a colon-separated list of directories in which the
85     <c>info</c> command searches for the info pages.
86     </ti>
87     </tr>
88     <tr>
89     <ti>PAGER</ti>
90     <ti>
91     This variable contains the path to the program used to list the contents of
92     files through (such as <c>less</c> or <c>more</c>).
93     </ti>
94     </tr>
95     <tr>
96     <ti>EDITOR</ti>
97     <ti>
98     This variable contains the path to the program used to change the contents
99     of files with (such as <c>nano</c> or <c>vi</c>).
100     </ti>
101     </tr>
102     <tr>
103     <ti>KDEDIRS</ti>
104     <ti>
105     This variable contains a colon-separated list of directories which contain
106     KDE-specific material.
107     </ti>
108     </tr>
109     <tr>
110     <ti>CONFIG_PROTECT</ti>
111     <ti>
112     This variable contains a <e>space</e>-delimited list of directories which
113     should be protected by Portage during updates.
114     </ti>
115     </tr>
116     <tr>
117     <ti>CONFIG_PROTECT_MASK</ti>
118     <ti>
119     This variable contains a <e>space</e>-delimited list of directories which
120     should not be protected by Portage during updates.
121     </ti>
122     </tr>
123     </table>
124    
125     <p>
126     Below you will find an example definition of all these variables:
127     </p>
128    
129     <pre caption="Example definitions">
130     PATH="/bin:/usr/bin:/usr/local/bin:/opt/bin:/usr/games/bin"
131     ROOTPATH="/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin"
132     LDPATH="/lib:/usr/lib:/usr/local/lib:/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
133     MANPATH="/usr/share/man:/usr/local/share/man"
134     INFODIR="/usr/share/info:/usr/local/share/info"
135     PAGER="/usr/bin/less"
136     EDITOR="/usr/bin/vim"
137 swift 1.4 KDEDIRS="/usr"
138     CONFIG_PROTECT="/usr/X11R6/lib/X11/xkb /opt/tomcat/conf \
139     /usr/kde/3.1/share/config /usr/share/texmf/tex/generic/config/ \
140     /usr/share/texmf/tex/platex/config/ /usr/share/config"
141 nightmorph 1.18 CONFIG_PROTECT_MASK="/etc/gconf"
142 swift 1.2 </pre>
143    
144 swift 1.1 </body>
145     </subsection>
146     </section>
147     <section>
148     <title>Defining Variables Globally</title>
149     <subsection>
150     <title>The /etc/env.d Directory</title>
151     <body>
152    
153 swift 1.2 <p>
154     To centralise the definitions of these variables, Gentoo introduced the
155     <path>/etc/env.d</path> directory. Inside this directory you will find a number
156     of files, such as <path>00basic</path>, <path>05gcc</path>, etc. which contain
157     the variables needed by the application mentioned in their name.
158     </p>
159    
160     <p>
161     For instance, when you installed <c>gcc</c>, a file called <path>05gcc</path>
162     was created by the ebuild which contains the definitions of the following
163     variables:
164     </p>
165    
166 swift 1.7 <pre caption="/etc/env.d/05gcc">
167 swift 1.2 PATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
168     ROOTPATH="/usr/i686-pc-linux-gnu/gcc-bin/3.2"
169     MANPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/man"
170     INFOPATH="/usr/share/gcc-data/i686-pc-linux-gnu/3.2/info"
171     CC="gcc"
172     CXX="g++"
173     LDPATH="/usr/lib/gcc-lib/i686-pc-linux-gnu/3.2.3"
174     </pre>
175    
176     <p>
177     Other distributions tell you to change or add such environment variable
178     definitions in <path>/etc/profile</path> or other locations. Gentoo on the other
179     hand makes it easy for you (and for Portage) to maintain and manage the
180     environment variables without having to pay attention to the numerous files that
181     can contain environment variables.
182     </p>
183    
184     <p>
185     For instance, when <c>gcc</c> is updated, the <path>/etc/env.d/05gcc</path> file
186     is updated too without requesting any user-interaction.
187     </p>
188    
189     <p>
190 neysx 1.8 This not only benefits Portage, but also you, as user. Occasionally you might
191 swift 1.2 be asked to set a certain environment variable system-wide. As an example we
192 neysx 1.8 take the <c>http_proxy</c> variable. Instead of messing about with
193 swift 1.2 <path>/etc/profile</path>, you can now just create a file
194     (<path>/etc/env.d/99local</path>) and enter your definition(s) in it:
195     </p>
196    
197     <pre caption="/etc/env.d/99local">
198     http_proxy="proxy.server.com:8080"
199     </pre>
200    
201     <p>
202     By using the same file for all your variables, you have a quick overview on the
203     variables you have defined yourself.
204     </p>
205    
206 swift 1.1 </body>
207     </subsection>
208     <subsection>
209     <title>The env-update Script</title>
210     <body>
211    
212 swift 1.2 <p>
213     Several files in <path>/etc/env.d</path> define the <c>PATH</c> variable. This
214 neysx 1.8 is not a mistake: when you run <c>env-update</c>, it will append the several
215 swift 1.2 definitions before it updates the environment variables, thereby making it easy
216     for packages (or users) to add their own environment variable settings without
217     interfering with the already existing values.
218     </p>
219    
220     <p>
221 neysx 1.16 The <c>env-update</c> script will append the values in the alphabetical order
222     of the <path>/etc/env.d</path> files. The file names must begin with two
223     decimal digits.
224 swift 1.2 </p>
225    
226     <pre caption="Update order used by env-update">
227     00basic 99kde-env 99local
228     +-------------+----------------+-------------+
229     PATH="/bin:/usr/bin:/usr/kde/3.2/bin:/usr/local/bin"
230     </pre>
231    
232     <p>
233 swift 1.12 The concatenation of variables does not always happen, only with the following
234 swift 1.23 variables: <c>ADA_INCLUDE_PATH</c>, <c>ADA_OBJECTS_PATH</c>, <c>CLASSPATH</c>,
235     <c>KDEDIRS</c>, <c>PATH</c>, <c>LDPATH</c>, <c>MANPATH</c>,
236 neysx 1.21 <c>INFODIR</c>, <c>INFOPATH</c>, <c>ROOTPATH</c>, <c>CONFIG_PROTECT</c>,
237 swift 1.23 <c>CONFIG_PROTECT_MASK</c>, <c>PRELINK_PATH</c>, <c>PRELINK_PATH_MASK</c>,
238     <c>PKG_CONFIG_PATH</c> and <c>PYTHONPATH</c>.
239 neysx 1.21 For all other variables the latest defined value (in alphabetical order of the
240     files in <path>/etc/env.d</path>) is used.
241 swift 1.12 </p>
242    
243     <p>
244 swift 1.23 You can add more variables into this list of concatenate-variables by adding the
245     variable name to either <c>COLON_SEPARATED</c> or <c>SPACE_SEPARATED</c>
246     variables (also inside an env.d file).
247     </p>
248    
249     <p>
250 swift 1.2 When you run <c>env-update</c>, the script will create all environment variables
251     and place them in <path>/etc/profile.env</path> (which is used by
252     <path>/etc/profile</path>). It will also extract the information from the
253     <c>LDPATH</c> variable and use that to create <path>/etc/ld.so.conf</path>.
254     After this, it will run <c>ldconfig</c> to recreate the
255     <path>/etc/ld.so.cache</path> file used by the dynamical linker.
256     </p>
257    
258     <p>
259 swift 1.3 If you want to notice the effect of <c>env-update</c> immediately after you run
260     it, execute the following command to update your environment. Users who have
261 swift 1.2 installed Gentoo themselves will probably remember this from the installation
262     instructions:
263     </p>
264    
265     <pre caption="Updating the environment">
266     # <i>env-update &amp;&amp; source /etc/profile</i>
267     </pre>
268    
269 smithj 1.13 <note>
270 smithj 1.14 The above command only updates the variables in your current terminal,
271     <e>new</e> consoles, and their children. Thus, if you are working in X11, you
272     will need to either type <c>source /etc/profile</c> in every new terminal you
273     open or restart X so that all new terminals source the new variables. If you
274     use a login manager, become root and type <c>/etc/init.d/xdm restart</c>. If
275     not, you will need to logout and log back in for X to spawn children with the
276     new variable values.
277 smithj 1.13 </note>
278    
279 nightmorph 1.22 <impo>
280     You cannot use shell variables when defining other variables. This means things
281     like <c>FOO="$BAR"</c> (where <c>$BAR</c> is another variable) are forbidden.
282     </impo>
283    
284 swift 1.1 </body>
285     </subsection>
286     </section>
287     <section>
288     <title>Defining Variables Locally</title>
289     <subsection>
290     <title>User Specific</title>
291     <body>
292    
293 swift 1.2 <p>
294     You do not always want to define an environment variable globally. For instance,
295 swift 1.15 you might want to add <path>/home/my_user/bin</path> and the current working
296     directory (the directory you are in) to the <c>PATH</c> variable
297 swift 1.2 but don't want all other users on your system to have that in their <c>PATH</c>
298     too. If you want to define an environment variable locally, you should use
299     <path>~/.bashrc</path> or <path>~/.bash_profile</path>:
300     </p>
301    
302     <pre caption="Extending PATH for local usage in ~/.bashrc">
303 swift 1.15 <comment>(A colon followed by no directory is treated as the current working directory)</comment>
304     PATH="${PATH}:/home/my_user/bin:"
305 swift 1.2 </pre>
306    
307     <p>
308     When you relogin, your <c>PATH</c> variable will be updated.
309     </p>
310    
311 swift 1.1 </body>
312     </subsection>
313     <subsection>
314     <title>Session Specific</title>
315     <body>
316 swift 1.2
317     <p>
318     Sometimes even stricter definitions are requested. You might want to be able to
319     use binaries from a temporary directory you created without using the path to
320 neysx 1.8 the binaries themselves or editing <path>~/.bashrc</path> for the short time
321 swift 1.2 you need it.
322     </p>
323    
324     <p>
325     In this case, you can just define the <c>PATH</c> variable in your current
326     session by using the <c>export</c> command. As long as you don't log out, the
327     <c>PATH</c> variable will be using the temporary settings.
328     </p>
329    
330     <pre caption="Defining a session-specific environment variable">
331     # <i>export PATH="${PATH}:/home/my_user/tmp/usr/bin"</i>
332     </pre>
333 swift 1.1
334     </body>
335     </subsection>
336     </section>
337     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20