doc/build/html/commands/environ.html

   1
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6   <head>
   7     <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
   8     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   9     <title>Command environ &#8212; salomeTools 5.0.0dev documentation</title>
  10     <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
  11     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  12     <script type="text/javascript" src="../_static/documentation_options.js"></script>
  13     <script type="text/javascript" src="../_static/jquery.js"></script>
  14     <script type="text/javascript" src="../_static/underscore.js"></script>
  15     <script type="text/javascript" src="../_static/doctools.js"></script>
  16     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
  17     <link rel="index" title="Index" href="../genindex.html" />
  18     <link rel="search" title="Search" href="../search.html" />
  19     <link rel="next" title="Command clean" href="clean.html" />
  20     <link rel="prev" title="Command log" href="log.html" />
  21
  22   <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  23
  24
  25   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
  26
  27   </head><body>
  28
  29
  30     <div class="document">
  31       <div class="documentwrapper">
  32         <div class="bodywrapper">
  33           <div class="body" role="main">
  34
  35   <div class="section" id="command-environ">
  36 <h1>Command environ<a class="headerlink" href="#command-environ" title="Permalink to this headline">¶</a></h1>
  37 <div class="section" id="description">
  38 <h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
  39 <p>The <strong>environ</strong> command generates the environment files used
  40 to run and compile your application (as <a class="reference external" href="http://www.salome-platform.org">SALOME</a> is an example).</p>
  41 <div class="admonition note">
  42 <p class="first admonition-title">Note</p>
  43 <p>these files are <strong>not</strong> required,
  44 salomeTool set the environment himself, when compiling.
  45 And so does the salome launcher.</p>
  46 <p class="last">These files are useful when someone wants to check the environment.
  47 They could be used in debug mode to set the environment for <em>gdb</em>.</p>
  48 </div>
  49 <p>The configuration part at the end of this page explains how
  50 to specify the environment used by sat (at build or run time),
  51 and saved in some files by <em>sat environ</em> command.</p>
  52 </div>
  53 <div class="section" id="usage">
  54 <h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
  55 <ul>
  56 <li><p class="first">Create the shell environment files of the application:</p>
  57 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sat</span> <span class="n">environ</span> <span class="o">&lt;</span><span class="n">application</span><span class="o">&gt;</span>
  58 </pre></div>
  59 </div>
  60 </li>
  61 <li><p class="first">Create the environment files of the application for a given shell.
  62 Options are bash, bat (for windows) and cfg (the configuration format used by <a class="reference external" href="http://www.salome-platform.org">SALOME</a>):</p>
  63 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sat</span> <span class="n">environ</span> <span class="o">&lt;</span><span class="n">application</span><span class="o">&gt;</span> <span class="o">--</span><span class="n">shell</span> <span class="p">[</span><span class="n">bash</span><span class="o">|</span><span class="n">cfg</span><span class="o">|</span><span class="nb">all</span><span class="p">]</span>
  64 </pre></div>
  65 </div>
  66 </li>
  67 <li><p class="first">Use a different prefix for the files (default is ‘env’):</p>
  68 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># This will create file &lt;prefix&gt;_launch.sh, &lt;prefix&gt;_build.sh</span>
  69 sat environ &lt;application&gt; --prefix &lt;prefix&gt;
  70 </pre></div>
  71 </div>
  72 </li>
  73 <li><p class="first">Use a different target directory for the files:</p>
  74 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># This will create file env_launch.sh, env_build.sh</span>
  75 <span class="c1"># in the directory corresponding to &lt;path&gt;</span>
  76 sat environ &lt;application&gt; --target &lt;path&gt;
  77 </pre></div>
  78 </div>
  79 </li>
  80 <li><p class="first">Generate the environment files only with the given products:</p>
  81 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># This will create the environment files only for the given products</span>
  82 <span class="c1"># and their prerequisites.</span>
  83 <span class="c1"># It is useful when you want to visualise which environment uses</span>
  84 <span class="c1"># sat to compile a given product.</span>
  85 sat environ &lt;application&gt; --product &lt;product1&gt;,&lt;product2&gt;, ...
  86 </pre></div>
  87 </div>
  88 </li>
  89 </ul>
  90 </div>
  91 <div class="section" id="configuration">
  92 <h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2>
  93 <p>The specification of the environment can be done through several mechanisms.</p>
  94 <ol class="arabic simple">
  95 <li>For salome products (the products with the property <code class="docutils literal notranslate"><span class="pre">is_SALOME_module</span></code> as <code class="docutils literal notranslate"><span class="pre">yes</span></code>) the environment is set automatically by sat, in respect with <a class="reference external" href="http://www.salome-platform.org">SALOME</a> requirements.</li>
  96 <li>For other products, the environment is set with the use of the environ section within the pyconf file of the product. The user has two possibilities, either set directly the environment within the section, or specify a python script which wil be used to set the environment programmatically.</li>
  97 </ol>
  98 <p>Within the section, the user can define environment variables. He can also modify PATH variables, by appending or prepending directories.
  99 In the following example, we prepend <em>&lt;install_dir&gt;/lib</em> to <code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code> (note the <em>left first</em> underscore), append <em>&lt;install_dir&gt;/lib</em> to <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> (note the <em>right last</em> underscore), and set <code class="docutils literal notranslate"><span class="pre">LAPACK_ROOT_DIR</span></code> to <em>&lt;install_dir&gt;</em>:</p>
 100 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>environ :
 101 <span class="o">{</span>
 102   _LD_LIBRARY_PATH : <span class="nv">$install_dir</span> + <span class="nv">$VARS</span>.sep + <span class="s2">&quot;lib&quot;</span>
 103   PYTHONPATH_ : <span class="nv">$install_dir</span> + <span class="nv">$VARS</span>.sep + <span class="s2">&quot;lib&quot;</span>
 104   LAPACK_ROOT_DIR : <span class="nv">$install_dir</span>
 105 <span class="o">}</span>
 106 </pre></div>
 107 </div>
 108 <p>It is possible to distinguish the build environment from the launch environment: use a subsection called <em>build</em> or <em>launch</em>. In the example below, <code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code> and <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> are only modified at run time, not at compile time:</p>
 109 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>environ :
 110 <span class="o">{</span>
 111   build :
 112   <span class="o">{</span>
 113     LAPACK_ROOT_DIR : <span class="nv">$install_dir</span>
 114   <span class="o">}</span>
 115   launch :
 116   <span class="o">{</span>
 117     LAPACK_ROOT_DIR : <span class="nv">$install_dir</span>
 118     _LD_LIBRARY_PATH : <span class="nv">$install_dir</span> + <span class="nv">$VARS</span>.sep + <span class="s2">&quot;lib&quot;</span>
 119     PYTHONPATH_ : <span class="nv">$install_dir</span> + <span class="nv">$VARS</span>.sep + <span class="s2">&quot;lib&quot;</span>
 120   <span class="o">}</span>
 121 <span class="o">}</span>
 122 </pre></div>
 123 </div>
 124 <ol class="arabic simple" start="3">
 125 <li>The last possibility is to set the environment with a python script. The script should be provided in the <em>products/env_scripts</em> directory of the sat project, and its name is specified in the environment section with the key <code class="docutils literal notranslate"><span class="pre">environ.env_script</span></code>:</li>
 126 </ol>
 127 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">environ</span> <span class="p">:</span>
 128 <span class="p">{</span>
 129   <span class="n">env_script</span> <span class="p">:</span> <span class="s1">&#39;lapack.py&#39;</span>
 130 <span class="p">}</span>
 131 </pre></div>
 132 </div>
 133 <p>Please note that the two modes are complementary and are both taken into account.
 134 Most of the time, the first mode is sufficient.</p>
 135 <p>The second mode can be used when the environment has to be set programmatically.
 136 The developer implements a handle (as a python method)
 137 which is called by sat to set the environment.
 138 Here is an example:</p>
 139 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
 140 <span class="c1">#-*- coding:utf-8 -*-</span>
 141
 142 <span class="kn">import</span> <span class="nn">os.path</span>
 143 <span class="kn">import</span> <span class="nn">platform</span>
 144
 145 <span class="k">def</span> <span class="nf">set_env</span><span class="p">(</span><span class="n">env</span><span class="p">,</span> <span class="n">prereq_dir</span><span class="p">,</span> <span class="n">version</span><span class="p">):</span>
 146     <span class="n">env</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s2">&quot;TRUST_ROOT_DIR&quot;</span><span class="p">,</span><span class="n">prereq_dir</span><span class="p">)</span>
 147     <span class="n">env</span><span class="o">.</span><span class="n">prepend</span><span class="p">(</span><span class="s1">&#39;PATH&#39;</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">prereq_dir</span><span class="p">,</span> <span class="s1">&#39;bin&#39;</span><span class="p">))</span>
 148     <span class="n">env</span><span class="o">.</span><span class="n">prepend</span><span class="p">(</span><span class="s1">&#39;PATH&#39;</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">prereq_dir</span><span class="p">,</span> <span class="s1">&#39;include&#39;</span><span class="p">))</span>
 149     <span class="n">env</span><span class="o">.</span><span class="n">prepend</span><span class="p">(</span><span class="s1">&#39;LD_LIBRARY_PATH&#39;</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">prereq_dir</span><span class="p">,</span> <span class="s1">&#39;lib&#39;</span><span class="p">))</span>
 150     <span class="k">return</span>
 151 </pre></div>
 152 </div>
 153 <p>SalomeTools defines four handles:</p>
 154 <ul class="simple">
 155 <li><strong>set_env(env, prereq_dir, version)</strong> : used at build and run time.</li>
 156 <li><strong>set_env_launch(env, prereq_dir, version)</strong> : used only at run time (if defined!)</li>
 157 <li><strong>set_env_build(env, prereq_dir, version)</strong> : used only at build time (if defined!)</li>
 158 <li><strong>set_native_env(env)</strong> : used only for native products, at build and run time.</li>
 159 </ul>
 160 </div>
 161 </div>
 162
 163
 164           </div>
 165         </div>
 166       </div>
 167       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 168         <div class="sphinxsidebarwrapper">
 169             <p class="logo"><a href="../index.html">
 170               <img class="logo" src="../_static/sat_v5.0.png" alt="Logo"/>
 171             </a></p>
 172   <h3><a href="../index.html">Table Of Contents</a></h3>
 173   <ul>
 174 <li><a class="reference internal" href="#">Command environ</a><ul>
 175 <li><a class="reference internal" href="#description">Description</a></li>
 176 <li><a class="reference internal" href="#usage">Usage</a></li>
 177 <li><a class="reference internal" href="#configuration">Configuration</a></li>
 178 </ul>
 179 </li>
 180 </ul>
 181 <div class="relations">
 182 <h3>Related Topics</h3>
 183 <ul>
 184   <li><a href="../index.html">Documentation overview</a><ul>
 185       <li>Previous: <a href="log.html" title="previous chapter">Command log</a></li>
 186       <li>Next: <a href="clean.html" title="next chapter">Command clean</a></li>
 187   </ul></li>
 188 </ul>
 189 </div>
 190   <div role="note" aria-label="source link">
 191     <h3>This Page</h3>
 192     <ul class="this-page-menu">
 193       <li><a href="../_sources/commands/environ.rst.txt"
 194             rel="nofollow">Show Source</a></li>
 195     </ul>
 196    </div>
 197 <div id="searchbox" style="display: none" role="search">
 198   <h3>Quick search</h3>
 199     <div class="searchformwrapper">
 200     <form class="search" action="../search.html" method="get">
 201       <input type="text" name="q" />
 202       <input type="submit" value="Go" />
 203       <input type="hidden" name="check_keywords" value="yes" />
 204       <input type="hidden" name="area" value="default" />
 205     </form>
 206     </div>
 207 </div>
 208 <script type="text/javascript">$('#searchbox').show(0);</script>
 209         </div>
 210       </div>
 211       <div class="clearer"></div>
 212     </div>
 213     <div class="footer">
 214       &copy;2018, CEA.
 215
 216       |
 217       Powered by <a href="http://sphinx-doc.org/">Sphinx 1.7.3</a>
 218       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
 219
 220       |
 221       <a href="../_sources/commands/environ.rst.txt"
 222           rel="nofollow">Page source</a>
 223     </div>
 224
 225
 226
 227
 228   </body>
 229 </html>