Skip to content

Commit

Permalink
Update documentation for modules
Browse files Browse the repository at this point in the history 
- Update the application development section to use modules instead of
  GOPATH and to use `go mod vendor` instead of `govendor` for vendoring.
- Move SoftHSM configuration information from "build" to "deveenv"
- Add jq to devenv prerequisites

Basically, fabric is a module and GOPATH should soon be a thing of the
past.

Signed-off-by: Matthew Sykes <sykesmat@us.ibm.com>
  • Loading branch information
@sykesm
sykesm committed Apr 15, 2020
1 parent 756a133 commit 252795a
Show file tree
Hide file tree
Showing 5 changed files with 113 additions and 114 deletions.
2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ check-go-version:
@scripts/check_go_version.sh $(GO_VER)

.PHONY: integration-test
integration-test: gotool.ginkgo ccenv-docker baseos-docker docker-thirdparty
integration-test: gotool.ginkgo baseos-docker ccenv-docker docker-thirdparty
./scripts/run-integration-tests.sh

.PHONY: unit-test
Expand Down
34 changes: 15 additions & 19 deletions docs/source/chaincode4ade.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,21 +75,22 @@ Choosing a Location for the Code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you haven't been doing programming in Go, you may want to make sure that
you have :ref:`Go` installed and your system properly configured.
you have :ref:`Go` installed and your system properly configured. We assume
you are using a version that supports modules.

Now, you will want to create a directory for your chaincode application as a
child directory of ``$GOPATH/src/``.
Now, you will want to create a directory for your chaincode application.

To keep things simple, let's use the following command:

.. code:: bash
mkdir -p $GOPATH/src/sacc && cd $GOPATH/src/sacc
mkdir sacc && cd sacc
Now, let's create the source file that we'll fill in with code:
Now, let's create the module and the source file that we'll fill in with code:

.. code:: bash
go mod init sacc
touch sacc.go
Housekeeping
Expand Down Expand Up @@ -416,24 +417,19 @@ To add the client identity shim extension to your chaincode as a dependency, see

Managing external dependencies for chaincode written in Go
----------------------------------------------------------
Your Go chaincode requires packages (like the chaincode shim) that are not part
of the Go standard library. These packages must be included in your chaincode
package.

There are `many tools available <https://github.com/golang/go/wiki/PackageManagementTools>`__
for managing (or "vendoring") these dependencies. The following demonstrates how to use
``govendor``:
Your Go chaincode depends on Go packages (like the chaincode shim) that are not
part of the standard library. The source to these packages must be included in
your chaincode package when it is installed to a peer. If you have scructured
your chaincode as a module, the easiest way to do this is to "vendor" the
dependencies with ``go mod vendor`` before packaging your chaincode.

.. code:: bash
govendor init
govendor add +external // Add all external package, or
govendor add github.com/external/pkg // Add specific external package
go mod tidy
go mod vendor
This imports the external dependencies into a local ``vendor`` directory.
If you are vendoring the Fabric shim or shim extensions, clone the
Fabric repository to your $GOPATH/src/github.com/hyperledger directory,
before executing the govendor commands.
This places the external dependencies for your chaincode into a local ``vendor``
directory.

Once dependencies are vendored in your chaincode directory, ``peer chaincode package``
and ``peer chaincode install`` operations will then include code associated with the
Expand Down
45 changes: 1 addition & 44 deletions docs/source/dev-setup/build.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ To build Hyperledger Fabric:

::

cd $GOPATH/src/github.com/hyperledger/fabric
make dist-clean all

Building the documentation
Expand Down Expand Up @@ -42,52 +41,10 @@ to incorporate the changes.
Running the unit tests
~~~~~~~~~~~~~~~~~~~~~~

Before running the unit tests, a PKCS #11 cryptographic token implementation
must be installed and configured. The PKCS #11 API is used by the bccsp
component of Fabric to interact with devices, such as hardware security modules
(HSMs), that store cryptographic information and perform cryptographic
computations. For test environments, SoftHSM can be used to satisfy this
requirement.

SoftHSM can be installed with the following commands:

::

sudo apt install libsofthsm2 # Ubuntu
sudo yum install softhsm # CentOS
brew install softhsm # macOS

Once SoftHSM is installed, additional configuration may be required. For
example, the default configuration file stores token data in a system directory
that unprivileged users are unable to write to.

Configuration typically involves copying ``/etc/softhsm2.conf`` to
``$HOME/.config/softhsm2/softhsm2.conf`` and changing ``directories.tokendir``
to an appropriate location. Please see the man page for ``softhsm2.conf`` for
details.

After SoftHSM has been configured, the following command can be used to
initialize the required token:

::

softhsm2-util --init-token --slot 0 --label "ForFabric" --so-pin 1234 --pin 98765432

If the test cannot find libsofthsm2.so in your environment, specify its path,
the PIN and the label of the token through environment variables. For example,
on macOS:

::

export PKCS11_LIB="/usr/local/Cellar/softhsm/2.5.0/lib/softhsm/libsofthsm2.so"
export PKCS11_PIN=98765432
export PKCS11_LABEL="ForFabric"

Use the following sequence to run all unit tests:
Use the following command to run all unit tests:

::

cd $GOPATH/src/github.com/hyperledger/fabric
make unit-test

To run a subset of tests, set the TEST_PKGS environment variable.
Expand Down
130 changes: 85 additions & 45 deletions docs/source/dev-setup/devenv.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,95 +4,135 @@ Setting up the development environment
Prerequisites
~~~~~~~~~~~~~

- Git client, Go, and Docker as described at :doc:`../prereqs`
- Git client
- `Go <https://golang.org/dl/>`__ version 1.14.x
- `Docker <https://docs.docker.com/get-docker/>`__ version 18.03 or later
- (macOS)
`Xcode <https://itunes.apple.com/us/app/xcode/id497799835?mt=12>`__
must be installed
- (macOS) you may need to install gnutar, as macOS comes with bsdtar
as the default, but the build uses some gnutar flags. You can use
Homebrew to install it as follows:
- (macOS) GNU tar. You can use `Homebrew <https://brew.sh/>`__ to install
it as follows:

::

brew install gnu-tar

- (macOS) If you install gnutar, you should prepend the "gnubin"
directory to the $PATH environment variable with something like:
- (macOS) If you've installed GNU tar, you should prepend the "gnubin"
directory to your $PATH with something like:

::

export PATH=/usr/local/opt/gnu-tar/libexec/gnubin:$PATH

- (macOS) `Libtool <https://www.gnu.org/software/libtool/>`__. You can use
- `Libtool <https://www.gnu.org/software/libtool/>`__. You can use
Homebrew to install it as follows:

::

brew install libtool

- (only if using Vagrant) - `Vagrant <https://www.vagrantup.com/>`__ -
1.9 or later
- (only if using Vagrant) -
`VirtualBox <https://www.virtualbox.org/>`__ - 5.0 or later
- BIOS Enabled Virtualization - Varies based on hardware
- `SoftHSM <https://github.com/opendnssec/SoftHSMv2>`__. You can use
Homebrew or apt to install it as follows:

::

brew install softhsm # macOS
sudo apt-get install libsofthsm2 # Ubuntu

- Note: The BIOS Enabled Virtualization may be within the CPU or
Security settings of the BIOS
- `jq <https://stedolan.github.io/jq/download/>`__. You can use
Homebrew to install it as follows:

::

brew install jq

Steps
~~~~~

Set your GOPATH
^^^^^^^^^^^^^^^
Clone the Hyperledger Fabric source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First navigate to https://github.com/hyperledger/fabric and fork the fabric
repository using the fork button in the top-right corner. After forking, clone
the repository.

::

mkdir -p github.com/<your_github_userid>
cd github.com/<your_github_userid>
git clone https://github.com/<your_github_userid>/fabric

.. note::
If you are running Windows, before cloning the repository, run thefollowing
command:

::

git config --get core.autocrlf

If ``core.autocrlf`` is set to ``true``, you must set it to ``false`` by
running:

::

git config --global core.autocrlf false

Make sure you have properly setup your Host's `GOPATH environment
variable <https://github.com/golang/go/wiki/GOPATH>`__. This allows for
both building within the Host and the VM.
Configure SoftHSM
^^^^^^^^^^^^^^^^^

In case you installed Go into a different location from the standard one
your Go distribution assumes, make sure that you also set `GOROOT
environment variable <https://golang.org/doc/install#install>`__.
A PKCS #11 cryptographic token implementation is required to run the unit
tests. The PKCS #11 API is used by the bccsp component of Fabric to interact
with hardware security modules (HSMs) that store cryptographic information and
perform cryptographic computations. For test environments, SoftHSM can be used
to satisfy this requirement.

Note to Windows users
^^^^^^^^^^^^^^^^^^^^^
SoftHSM generally requires additional configuration before it can be used. For
example, the default configuration will attempt to store token data in a system
directory that unprivileged users are unable to write to.

If you are running Windows, before running any ``git clone`` commands,
run the following command.
SoftHSM configuration typically involves copying ``/etc/softhsm2.conf`` to
``$HOME/.config/softhsm2/softhsm2.conf`` and changing ``directories.tokendir``
to an appropriate location. Please see the man page for ``softhsm2.conf`` for
details.

After SoftHSM has been configured, the following command can be used to
initialize the token required by the unit tests:

::

git config --get core.autocrlf
softhsm2-util --init-token --slot 0 --label "ForFabric" --so-pin 1234 --pin 98765432

If ``core.autocrlf`` is set to ``true``, you must set it to ``false`` by
running
If tests are unable to locate the libsofthsm2.so library in your environment,
specify the library path, the PIN, and the label of your token in the
appropriate environment variables. For example, on macOS:

::

git config --global core.autocrlf false
export PKCS11_LIB="/usr/local/Cellar/softhsm/2.5.0/lib/softhsm/libsofthsm2.so"
export PKCS11_PIN=98765432
export PKCS11_LABEL="ForFabric"

If you continue with ``core.autocrlf`` set to ``true``, the
``vagrant up`` command will fail with the error:
Install the development tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``./setup.sh: /bin/bash^M: bad interpreter: No such file or directory``
Once the repository is cloned, you can use ``make`` to install some of the
tools used in the development environment. By default, these tools will be
installed into ``$HOME/go/bin``. Please be sure your ``PATH`` includes that
directory.

Cloning the Hyperledger Fabric source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::

First navigate to https://github.com/hyperledger/fabric and fork the
fabric repository using the fork button in the top-right corner
make gotools

Since Hyperledger Fabric is written in ``Go``, you'll need to
clone the forked repository to your $GOPATH/src directory. If your $GOPATH
has multiple path components, then you will want to use the first one.
There's a little bit of setup needed:
After installing the tools, the build environment can be verified by running a
a few commands.

::

cd $GOPATH/src
mkdir -p github.com/<your_github_userid>
cd github.com/<your_github_userid>
git clone https://github.com/<your_github_userid>/fabric
make basic-checks docker-test-prereqs
ginkgo -r ./integration/nwo

If those commands completely successfully, you're ready to Go!

.. Licensed under Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/
16 changes: 11 additions & 5 deletions docs/source/style-guides/go-style.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,11 +60,17 @@ in `GoDoc <https://godoc.org/github.com/hyperledger/fabric>`_.
Adding or updating Go packages
------------------------------

Hyperledger Fabric vendors dependencies. This means that all required packages
reside in the ``$GOPATH/src/github.com/hyperledger/fabric/vendor`` folder. Go
will use packages in this folder instead of the GOPATH when the ``go install``
or ``go build`` commands are executed. To manage the packages in the ``vendor``
folder, we use `dep <https://golang.github.io/dep/>`__.
Hyperledger Fabric uses go modules to manage and vendor its dependencies. This
means that all of the external packages required to build our binaries reside
in the ``vendor`` folder at the top of the repository. Go uses the packages in
this folder instead of the module cache when ``go`` commands are executed.

If a code change results in a new or updated dependency, please be sure to run
``go mod tidy`` and ``go mod vendor`` to keep the ``vendor`` folder and
dependency metadata up to date.

See the `Go Modules Wiki <https://github.com/golang/go/wiki/Modules>`__ for
additional information.

.. Licensed under Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/

0 comments on commit 252795a

Please sign in to comment.