/[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.18 - (hide annotations) (download) (as text)
Mon Mar 27 19:48:30 2006 UTC (8 years ago) by nightmorph
Branch: MAIN
Changes since 1.17: +2 -2 lines
File MIME type: application/xml
Typo fix for bug 127513, thanks to achumakov for reporting

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

  ViewVC Help
Powered by ViewVC 1.1.20