Updated virtualrunenv generator and some fixes (conan-io#677)

* updated virtualrunenv generator

* rewrite using virtualrunenv and runenvironment helper

* fix

* mac fix

Author: danimtb

howtos/custom_generators.rst

@@ -42,10 +42,10 @@ that file. The **name of the generator** itself will be taken from the class nam
         def content(self):     
             return "whatever contents the generator produces"
             
-This class is just included in a ``conanfile.py`` that must contain also a ``Conanfile`` class
+This class is just included in a ``conanfile.py`` that must contain also a ``ConanFile`` class
 that implements the package itself, with the name of the package, the version, etc. This
 class typically has no ``source()``, ``build()``, ``package()``, and even the ``package_info()`` method is
-overriden as it doesn't have to define any include paths or library paths.
+overridden as it doesn't have to define any include paths or library paths.
 
 If you want to create a generator that creates more than one file, you can leave the ``filename()`` empty, and return a dictionary of
 filenames->contents in the ``content()`` method:

howtos/manage_shared_libraries/env_vars.rst

@@ -24,11 +24,9 @@ the right environment variable set, so they will be able to locate the (A) share
 Similarly if you use the :ref:`virtualenv generator<virtual_environment_generator>` and you
 activate it, you will get the paths needed to locate the shared libraries in your terminal.
 
-
 Example
 -------
 
-
 We are packaging a tool called ``toolA`` with a library and an executable that, for example, compress data.
 
 The package offers two flavors, shared library or static library (embedded in the executable of the tool and
@@ -49,7 +47,6 @@ you will need to have the shared library available.
         options = {"shared": [True, False]}
         default_options = "shared=False"
 
-
         def build(self):
             # build your shared library
 
@@ -65,40 +62,28 @@ you will need to have the shared library available.
             else:
                 ...
 
-
-        def package_info(self):
-            self.env_info.PATH.append(os.path.join(self.package_folder, "bin"))
-            if self.options.shared:
-                self.env_info.LD_LIBRARY_PATH.append(os.path.join(self.package_folder, "lib"))
-                self.env_info.DYLD_LIBRARY_PATH.append(os.path.join(self.package_folder, "lib"))
-
-
-
 Using the tool from a different package
 ---------------------------------------
 
 If we are creating now a package that uses the ``ToolA`` executable to compress some data. You can
-call directly to the ``toolA.exe``, the required environment variables to locate both the executable
-and the shared libraries are automatically available:
+execute directly ``toolA`` using RunEnvironment build helper to set the environment variables accordingly:
 
 .. code-block:: python
 
     import os
     from conans import tools, ConanFile
 
     class PackageB(ConanFile):
-        ....
         name = "packageB"
         version = "1.0"
         requires = "toolA/1.0@myuser/stable"
 
-
         def build(self):
-            ...
-            # we can call directly the ``toolA`` executable. the shared library will be located too
             exe_name = "toolA.exe" if self.settings.os == "Windows" else "toolA"
-            self.run("%s --someparams" % exe_name)
-            ...
+            env_build = RunEnvironment(self)
+            with tools.environment_append(env_build.vars):
+                self.run("%s --someparams" % exe_name)
+                ...
 
 Building an application using the shared library from ``toolA``
 ---------------------------------------------------------------
@@ -107,9 +92,8 @@ As we are building a final application, probably we will want to distribute it t
 shared library from the ``toolA``, so we can use the :ref:`Imports<imports_txt>` to import the required
 shared libraries to our user space.
 
-**conanfile.txt**
-
 .. code-block:: python
+   :caption: *conanfile.txt*
 
     [requires]
     toolA/1.0@myuser/stable
@@ -125,8 +109,7 @@ shared libraries to our user space.
     lib, *.dylib* -> ./bin # Copies all dylib files from packages lib folder to my "bin" folder
     lib, *.so* -> ./bin # Copies all dylib files from packages lib folder to my "bin" folder
 
-
-**In the terminal window and build the project:**
+Now you can build the project:
 
 .. code-block:: bash
 
@@ -146,67 +129,35 @@ In Linux you still need to set the ``LD_LIBRARY_PATH``, or in OSX, the ``DYLD_LI
 
    $ cd bin && LD_LIBRARY_PATH=$(pwd) && ./mytool
 
-
 Using shared libraries from dependencies
-------------------------------------------
+----------------------------------------
 
 If you are executing something that depends on shared libraries belonging to your dependencies, such shared libraries have to be found at
 runtime. In Windows, it is enough if the package added its binary folder to the system ``PATH``. In Linux and OSX, it is necessary that the
 ``LD_LIBRARY_PATH`` and ``DYLD_LIBRARY_PATH`` environment variables are used.
 
 Security restrictions might apply in OSX
 (`read this thread <https://stackoverflow.com/questions/35568122/why-isnt-dyld-library-path-being-propagated-here>`_), so the
-``DYLD_LIBRARY_PATH`` environment variable is not directly transferred to the child process. In that case, you have to use it explicitely in
-your conanfile.py:
+``DYLD_LIBRARY_PATH`` environment variable is not directly transferred to the child process. In that case, you have to use it explicitly in
+your *conanfile.py*:
 
 .. code-block:: python
 
     def test(self):
         # self.run('./myexe") # won't work, even if 'DYLD_LIBRARY_PATH' is in the env
-        self.run('DYLD_LIBRARY_PATH=%s ./myexe" % os.environ['DYLD_LIBRARY_PATH'])
-
-
-
-Using the **virtualenv** generator
-----------------------------------
-
-We could also use a :ref:`virtualenv generator<virtual_environment_generator>` to get the
-``toolA`` executable available:
-
-**conanfile.txt**
+        with tools.environment_append({"DYLD_LIBRARY_PATH": [self.deps_cpp_info["toolA"].lib_paths]}):
+            self.run('DYLD_LIBRARY_PATH=%s ./myexe" % os.environ['DYLD_LIBRARY_PATH'])
 
-.. code-block:: python
-
-    [requires]
-    toolA/1.0@myuser/stable
-
-    [options]
-    toolA:shared=True
+Or you could use ``RunEnvironment`` helper described above.
 
-    [generators]
-    virtualenv
+Using ``virtualrunenv`` generator
+---------------------------------
 
-
-**In the terminal window:**
-
-.. code-block:: bash
-
-    conan install .
-    source activate
-    toolA --someparams
-
-
-Using the **virtualrunenv** generator
--------------------------------------
-
-Even if ``toolA`` doesn't declare the variables in the ``package_info`` method, you can use
-the :ref:`virtualrunenv generator<virtual_run_environment_generator>`. It will set automatically
-the environment variables poiting to the "lib" and "bin" folders.
-
-
-**conanfile.txt**
+:ref:`virtualrunenv generator<virtual_run_environment_generator>` will set the environment variables ``PATH``, ``LD_LIBRARY_PATH``,
+``DYLD_LIBRARY_PATH`` pointing to *lib* and *bin* folders automatically.
 
 .. code-block:: python
+   :caption: *conanfile.txt*
 
     [requires]
     toolA/1.0@myuser/stable
@@ -215,14 +166,14 @@ the environment variables poiting to the "lib" and "bin" folders.
     toolA:shared=True
 
     [generators]
-    virtualenv
+    virtualrunenv
 
-
-**In the terminal window:**
+In the terminal window:
 
 .. code-block:: bash
 
-    conan install .
-    source activate
-    toolA --someparams
-
+    $ conan install .
+    $ source activate_run
+    $ toolA --someparams
+    # Only For Mac OS users to avoid restrictions:
+    $ DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH toolA --someparams

reference/conanfile/methods.rst

@@ -289,8 +289,8 @@ consumers can use those executables easily:
     # assuming the binaries are in the "bin" subfolder
     self.env_info.PATH.append(os.path.join(self.package_folder, "bin")
 
-The :ref:`virtualenv<virtual_environment_generator>` generator will use the self.env_info variables to prepare a script to activate/deactive
-a virtual environment.
+The :ref:`virtualenv<virtual_environment_generator>` generator will use the ``self.env_info`` variables to prepare a script to
+activate/deactive a virtual environment. However, this could be directly done using the :ref:`virtualrunenv_generator` generator.
 
 They will be automatically applied before calling the consumer *conanfile.py* methods ``source()``, ``build()``, ``package()`` and
 ``imports()``.