github.com/myafeier/fabric@v1.0.1-0.20170722181825-3a4b1f2bce86/docs/source/dev-setup/devenv.rst (about)

     1  Setting up the development environment
     2  --------------------------------------
     3  
     4  Overview
     5  ~~~~~~~~
     6  
     7  Prior to the v1.0.0 release, the development environment utilized Vagrant
     8  running an Ubuntu image, which in turn launched Docker containers as a
     9  means of ensuring a consistent experience for developers who might be
    10  working with varying platforms, such as macOS, Windows, Linux, or
    11  whatever. Advances in Docker have enabled native support on the most
    12  popular development platforms: macOS and Windows. Hence, we have
    13  reworked our build to take full advantage of these advances. While we
    14  still maintain a Vagrant based approach that can be used for older
    15  versions of macOS and Windows that Docker does not support, we strongly
    16  encourage that the non-Vagrant development setup be used.
    17  
    18  Note that while the Vagrant-based development setup could not be used in
    19  a cloud context, the Docker-based build does support cloud platforms
    20  such as AWS, Azure, Google and IBM to name a few. Please follow the
    21  instructions for Ubuntu builds, below.
    22  
    23  Prerequisites
    24  ~~~~~~~~~~~~~
    25  
    26  -  `Git client <https://git-scm.com/downloads>`__
    27  -  `Go <https://golang.org/>`__ - 1.7 or later (for releases before
    28     v1.0, 1.6 or later)
    29  -  For macOS,
    30     `Xcode <https://itunes.apple.com/us/app/xcode/id497799835?mt=12>`__
    31     must be installed
    32  -  `Docker <https://www.docker.com/products/overview>`__ - 1.12 or later
    33  -  `Docker Compose <https://docs.docker.com/compose/>`__ - 1.8.1 or later
    34  -  `Pip <https://pip.pypa.io/en/stable/installing/>`__
    35  -  (macOS) you may need to install gnutar, as macOS comes with bsdtar
    36     as the default, but the build uses some gnutar flags. You can use
    37     Homebrew to install it as follows:
    38  
    39  ::
    40  
    41      brew install gnu-tar --with-default-names
    42  
    43  -  (only if using Vagrant) - `Vagrant <https://www.vagrantup.com/>`__ -
    44     1.7.4 or later
    45  -  (only if using Vagrant) -
    46     `VirtualBox <https://www.virtualbox.org/>`__ - 5.0 or later
    47  -  BIOS Enabled Virtualization - Varies based on hardware
    48  
    49  -  Note: The BIOS Enabled Virtualization may be within the CPU or
    50     Security settings of the BIOS
    51  
    52  ``pip``, ``behave`` and ``docker-compose``
    53  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    54  
    55  ::
    56  
    57      pip install --upgrade pip
    58      pip install behave nose docker-compose
    59      pip install -I flask==0.10.1 python-dateutil==2.2 pytz==2014.3 pyyaml==3.10 couchdb==1.0 flask-cors==2.0.1 requests==2.4.3 pyOpenSSL==16.2.0 pysha3==1.0b1 grpcio==1.0.4
    60  
    61      #PIP packages required for some behave tests
    62      pip install urllib3 ndg-httpsclient pyasn1 ecdsa python-slugify grpcio-tools jinja2 b3j0f.aop six
    63  
    64  Steps
    65  ~~~~~
    66  
    67  Set your GOPATH
    68  ^^^^^^^^^^^^^^^
    69  
    70  Make sure you have properly setup your Host's `GOPATH environment
    71  variable <https://github.com/golang/go/wiki/GOPATH>`__. This allows for
    72  both building within the Host and the VM.
    73  
    74  In case you installed Go into a different location from the standard one
    75  your Go distribution assumes, make sure that you also set `GOROOT
    76  environment variable <https://golang.org/doc/install#install>`__.
    77  
    78  Note to Windows users
    79  ^^^^^^^^^^^^^^^^^^^^^
    80  
    81  If you are running Windows, before running any ``git clone`` commands,
    82  run the following command.
    83  
    84  ::
    85  
    86      git config --get core.autocrlf
    87  
    88  If ``core.autocrlf`` is set to ``true``, you must set it to ``false`` by
    89  running
    90  
    91  ::
    92  
    93      git config --global core.autocrlf false
    94  
    95  If you continue with ``core.autocrlf`` set to ``true``, the
    96  ``vagrant up`` command will fail with the error:
    97  
    98  ``./setup.sh: /bin/bash^M: bad interpreter: No such file or directory``
    99  
   100  Cloning the Hyperledger Fabric source
   101  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   102  
   103  Since Hyperledger Fabric is written in ``Go``, you'll need to
   104  clone the source repository to your $GOPATH/src directory. If your $GOPATH
   105  has multiple path components, then you will want to use the first one.
   106  There's a little bit of setup needed:
   107  
   108  ::
   109  
   110      cd $GOPATH/src
   111      mkdir -p github.com/hyperledger
   112      cd github.com/hyperledger
   113  
   114  Recall that we are using ``Gerrit`` for source control, which has its
   115  own internal git repositories. Hence, we will need to clone from
   116  :doc:`Gerrit <../Gerrit/gerrit>`.
   117  For brevity, the command is as follows:
   118  
   119  ::
   120  
   121      git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/
   122  
   123  **Note:** Of course, you would want to replace ``LFID`` with your own
   124  :doc:`Linux Foundation ID <../Gerrit/lf-account>`.
   125  
   126  Bootstrapping the VM using Vagrant
   127  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   128  
   129  If you are planning on using the Vagrant developer environment, the
   130  following steps apply. **Again, we recommend against its use except for
   131  developers that are limited to older versions of macOS and Windows that
   132  are not supported by Docker for Mac or Windows.**
   133  
   134  ::
   135  
   136      cd $GOPATH/src/github.com/hyperledger/fabric/devenv
   137      vagrant up
   138  
   139  Go get coffee... this will take a few minutes. Once complete, you should
   140  be able to ``ssh`` into the Vagrant VM just created.
   141  
   142  ::
   143  
   144      vagrant ssh
   145  
   146  Once inside the VM, you can find the source under
   147  ``$GOPATH/src/github.com/hyperledger/fabric``. It is also mounted as
   148  ``/hyperledger``.
   149  
   150  Building Hyperledger Fabric
   151  ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   152  
   153  Once you have all the dependencies installed, and have cloned the
   154  repository, you can proceed to :doc:`build and test <build>` Hyperledger
   155  Fabric.
   156  
   157  Notes
   158  ~~~~~
   159  
   160  **NOTE:** Any time you change any of the files in your local fabric
   161  directory (under ``$GOPATH/src/github.com/hyperledger/fabric``), the
   162  update will be instantly available within the VM fabric directory.
   163  
   164  **NOTE:** If you intend to run the development environment behind an
   165  HTTP Proxy, you need to configure the guest so that the provisioning
   166  process may complete. You can achieve this via the *vagrant-proxyconf*
   167  plugin. Install with ``vagrant plugin install vagrant-proxyconf`` and
   168  then set the VAGRANT\_HTTP\_PROXY and VAGRANT\_HTTPS\_PROXY environment
   169  variables *before* you execute ``vagrant up``. More details are
   170  available here: https://github.com/tmatilai/vagrant-proxyconf/
   171  
   172  **NOTE:** The first time you run this command it may take quite a while
   173  to complete (it could take 30 minutes or more depending on your
   174  environment) and at times it may look like it's not doing anything. As
   175  long you don't get any error messages just leave it alone, it's all
   176  good, it's just cranking.
   177  
   178  **NOTE to Windows 10 Users:** There is a known problem with vagrant on
   179  Windows 10 (see
   180  `mitchellh/vagrant#6754 <https://github.com/mitchellh/vagrant/issues/6754>`__).
   181  If the ``vagrant up`` command fails it may be because you do not have
   182  the Microsoft Visual C++ Redistributable package installed. You can
   183  download the missing package at the following address:
   184  http://www.microsoft.com/en-us/download/details.aspx?id=8328
   185  
   186  .. Licensed under Creative Commons Attribution 4.0 International License
   187     https://creativecommons.org/licenses/by/4.0/
   188