github.com/hechain20/hechain@v0.0.0-20220316014945-b544036ba106/docs/source/dev-setup/devenv.rst (about)

     1  Setting up the development environment
     2  --------------------------------------
     3  
     4  Prerequisites
     5  ~~~~~~~~~~~~~
     6  
     7  In addition to the standard :doc:`../prereqs` for Fabric, the following prerequisites are also required:
     8  
     9  -  (macOS) `Xcode Command Line Tools <https://developer.apple.com/downloads/>`__
    10  -  (All platforms) `SoftHSM <https://github.com/opendnssec/SoftHSMv2>`__ use version 2.5 as 2.6 is not operable in this environment
    11  -  (All platforms) `jq <https://stedolan.github.io/jq/download/>`__
    12  
    13  For Linux platforms, including WSL2 on Windows, also required are various build tools such as gnu-make and 
    14  C compiler. On ubuntu and it's derivatives you can install the required toolset by using the command 
    15  ``sudo apt install build-essential``. Other distributions may already have the appropriate tools installed
    16  or provide a convenient way to install the various build tools.
    17  
    18  Steps
    19  ~~~~~
    20  
    21  Installing SoftHSM
    22  ^^^^^^^^^^^^^^^^^^
    23  Ensure you install ``2.5`` of softhsm, if you are using a distribution package manager such as ``apt`` on ubuntu
    24  or Homebrew on Mac OS, make sure that it offers this version otherwise you will need to install from source. Version 2.6
    25  of SoftHSM is known to have problems. Older versions than 2.5 may work however.
    26  
    27  When installing SoftHSM, you should note the path where the shared library ``libsofthsm2.so`` is installed
    28  you may need to have to provide this later in an environment variable to get the PKCS11 tests to pass.
    29  
    30  Install the Prerequisites using Homebrew on MacOS
    31  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    32  
    33  For macOS, `Homebrew <https://brew.sh>`__ can be used to manage the
    34  development prereqs (assuming that you would like to install the latest versions).
    35  The Xcode command line tools will be installed as part of the Homebrew installation.
    36  
    37  Once Homebrew is ready, installing the necessary prerequisites is very easy, for example:
    38  
    39  ::
    40  
    41      brew install git jq
    42      brew install --cask docker
    43  
    44  Go and SoftHSM are also available from Homebrew, but make sure you install the appropriate versions
    45  
    46  Docker Desktop must be launched to complete the installation, so be sure to open
    47  the application after installing it:
    48  
    49  ::
    50  
    51      open /Applications/Docker.app
    52  
    53  Developing on Windows
    54  ~~~~~~~~~~~~~~~~~~~~~
    55  
    56  It is recommended that all development be done within your WSL2 Linux distribution.
    57  
    58  Clone the Hechain source
    59  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    60  
    61  First navigate to https://github.com/hyperledger/fabric and fork the fabric
    62  repository using the fork button in the top-right corner. After forking, clone
    63  the repository.
    64  
    65  ::
    66  
    67      mkdir -p github.com/<your_github_userid>
    68      cd github.com/<your_github_userid>
    69      git clone https://github.com/<your_github_userid>/fabric
    70  
    71  
    72  Configure SoftHSM
    73  ^^^^^^^^^^^^^^^^^
    74  
    75  A PKCS #11 cryptographic token implementation is required to run the unit
    76  tests. The PKCS #11 API is used by the bccsp component of Fabric to interact
    77  with hardware security modules (HSMs) that store cryptographic information and
    78  perform cryptographic computations.  For test environments, SoftHSM can be used
    79  to satisfy this requirement.
    80  
    81  SoftHSM generally requires additional configuration before it can be used. For
    82  example, the default configuration will attempt to store token data in a system
    83  directory that unprivileged users are unable to write to.
    84  
    85  SoftHSM configuration typically involves copying ``/etc/softhsm/softhsm2.conf``
    86  (or ``/usr/local/etc/softhsm/softhsm2.conf`` for macOS) to
    87  ``$HOME/.config/softhsm2/softhsm2.conf`` and changing ``directories.tokendir``
    88  to an appropriate location. Please see the man page for ``softhsm2.conf`` for
    89  details.
    90  
    91  After SoftHSM has been configured, the following command can be used to
    92  initialize the token required by the unit tests:
    93  
    94  ::
    95  
    96      softhsm2-util --init-token --slot 0 --label ForFabric --so-pin 1234 --pin 98765432
    97  
    98  If tests are unable to locate the libsofthsm2.so library in your environment,
    99  specify the library path, the PIN, and the label of your token in the
   100  appropriate environment variables. For example, on macOS, depending on where the
   101  library has been installed:
   102  
   103  ::
   104  
   105      export PKCS11_LIB="/usr/local/Cellar/softhsm/2.6.1/lib/softhsm/libsofthsm2.so"
   106      export PKCS11_PIN=98765432
   107      export PKCS11_LABEL="ForFabric"
   108  
   109  If you installed SoftHSM on ubuntu from source then the environment variables may look like
   110  
   111  ::
   112  
   113      export PKCS11_LIB="/usr/local/lib/softhsm/libsofthsm2.so"
   114      export PKCS11_PIN=98765432
   115      export PKCS11_LABEL="ForFabric"
   116  
   117  
   118  The tests don't always clean up after themselves and, over time, this causes
   119  the PKCS #11 tests to take a long time to run. The easiest way to recover from
   120  this is to delete and recreate the token.
   121  
   122  ::
   123  
   124      softhsm2-util --delete-token --token ForFabric
   125      softhsm2-util --init-token --slot 0 --label ForFabric --so-pin 1234 --pin 98765432
   126  
   127  Debugging with ``pkcs11-spy``
   128  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   129  
   130  The `OpenSC Project <https://github.com/OpenSC/OpenSC>`__ provides a shared
   131  library called ``pkcs11-spy`` that logs all interactions between an application
   132  and a PKCS #11 module. This library can be very useful when troubleshooting
   133  interactions with a cryptographic token device or service.
   134  
   135  Once the library has been installed, configure Fabric to use ``pkcs11-spy`` as
   136  the PKCS #11 library and set the ``PKCS11SPY`` environment variable to the real
   137  library. For example:
   138  
   139  ::
   140  
   141      export PKCS11SPY="/usr/lib/softhsm/libsofthsm2.so"
   142      export PKCS11_LIB="/usr/lib/x86_64-linux-gnu/pkcs11/pkcs11-spy.so"
   143  
   144  
   145  Install the development tools
   146  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   147  
   148  Once the repository is cloned, you can use ``make`` to install some of the
   149  tools used in the development environment. By default, these tools will be
   150  installed into ``$HOME/go/bin``. Please be sure your ``PATH`` includes that
   151  directory.
   152  
   153  ::
   154  
   155      make gotools
   156  
   157  After installing the tools, the build environment can be verified by running a
   158  few commands.
   159  
   160  ::
   161  
   162      make basic-checks integration-test-prereqs
   163      ginkgo -r ./integration/nwo
   164  
   165  If those commands completely successfully, you're ready to Go!
   166  
   167  If you plan to use the Hechain application SDKs then be sure to check out their prerequisites in the Node.js SDK `README <https://github.com/hyperledger/fabric-sdk-node#build-and-test>`__, Java SDK `README <https://github.com/hyperledger/fabric-gateway-java/blob/main/README.md>`__, and Go SDK `README <https://github.com/hyperledger/fabric-sdk-go/blob/main/README.md>`__.
   168  
   169  .. Licensed under Creative Commons Attribution 4.0 International License
   170     https://creativecommons.org/licenses/by/4.0/