Skip to content

Commit

Permalink
Address windows platform in documentation
Browse files Browse the repository at this point in the history 
closes #2993
Signed-off-by: D <d_kelsey@uk.ibm.com>
(cherry picked from commit e7ebce1)
  • Loading branch information
@ale-linux
D authored and ale-linux committed Jan 27, 2022
1 parent 63a7779 commit 0e9cdb2
Show file tree
Hide file tree
Showing 4 changed files with 38 additions and 85 deletions.
64 changes: 13 additions & 51 deletions docs/source/dev-setup/devenv.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,16 @@ Setting up the development environment
Prerequisites
~~~~~~~~~~~~~

- `Git client <https://git-scm.com/downloads>`__
- `Go <https://golang.org/dl/>`__ version 1.17.x (recommended Go version can be found in project Makefile)
- `Docker <https://docs.docker.com/get-docker/>`__ version 18.03 or later
In addition to the standard :doc:`../prereqs` for Fabric, the following prerequisites are also required:

- (macOS) `Xcode Command Line Tools <https://developer.apple.com/downloads/>`__
- `SoftHSM <https://github.com/opendnssec/SoftHSMv2>`__ use version 2.5 as 2.6 is broken in this environment
- `jq <https://stedolan.github.io/jq/download/>`__
- (All platforms) `SoftHSM <https://github.com/opendnssec/SoftHSMv2>`__ use version 2.5 as 2.6 is not operable in this environment
- (All platforms) `jq <https://stedolan.github.io/jq/download/>`__

For Linux platforms, including WSL2 on Windows, also required are various build tools such as gnu-make and
C compiler. On ubuntu and it's derivatives you can install the required toolset by using the command
``sudo apt install build-essential``. Other distributions may already have the appropriate tools installed
or provide a convenient way to install the various build tools.

Steps
~~~~~
Expand Down Expand Up @@ -38,9 +41,9 @@ Once Homebrew is ready, installing the necessary prerequisites is very easy, for
brew install git jq
brew install --cask docker

Go and SoftHSM are akso available from Homebrew but make sure you install the appropriate versions
Go and SoftHSM are also available from Homebrew, but make sure you install the appropriate versions

Docker Desktop must be launched to complete the installation so be sure to open
Docker Desktop must be launched to complete the installation, so be sure to open
the application after installing it:

::
Expand All @@ -50,33 +53,7 @@ the application after installing it:
Developing on Windows
~~~~~~~~~~~~~~~~~~~~~

On Windows 10 you should use the native Docker distribution and you
may use the Windows PowerShell. However, for the ``binaries``
command to succeed you will still need to have the ``uname`` command
available. You can get it as part of Git but beware that only the
64bit version is supported.

Before running any ``git clone`` commands, run the following commands:

::

git config --global core.autocrlf false
git config --global core.longpaths true

You can check the setting of these parameters with the following commands:

::

git config --get core.autocrlf
git config --get core.longpaths

These need to be ``false`` and ``true`` respectively.

The ``curl`` command that comes with Git and Docker Toolbox is old and
does not handle properly the redirect used in
:doc:`../getting_started`. Make sure you have and use a newer version
which can be downloaded from the `cURL downloads page
<https://curl.haxx.se/download.html>`__
It is recommended that all development be done within your WSL2 Linux distribution.

Clone the Hyperledger Fabric source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -91,21 +68,6 @@ the repository.
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 the following
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


Configure SoftHSM
^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -176,8 +138,8 @@ library. For example:

::

export PKCS11_LIB="/usr/lib/softhsm/libsofthsm2.so"
export PKCS11SPY="/usr/lib/x86_64-linux-gnu/pkcs11/pkcs11-spy.so"
export PKCS11SPY="/usr/lib/softhsm/libsofthsm2.so"
export PKCS11_LIB="/usr/lib/x86_64-linux-gnu/pkcs11/pkcs11-spy.so"


Install the development tools
Expand Down
7 changes: 1 addition & 6 deletions docs/source/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,9 @@ curl -sSL https://bit.ly/2ysbOFE | bash -s -- 2.4.1 1.5.2

## Notes

### Windows considerations

The recommended directory on Windows is `%USERPROFILE%\go\src\github.com\<your_github_userid>`.
If using another directory, please consult the Docker documentation for [file sharing](https://docs.docker.com/docker-for-windows/#file-sharing) and the [GOPATH environment](https://golang.org/doc/gopath_code.html#GOPATH) documentation.

### Other considerations

* Setting GOPATH is not required when using Go modules in your projects, or when using the recommended directory. If you would like to use a different location for fabric-samples, you may set GOPATH to point to your specific go workspace. For example on macOS:
* Setting GOPATH is not required when using Go modules in your projects, or when using the recommended directory. If you would like to use a different location for fabric-samples, you may set GOPATH to point to your specific Go workspace. For example on macOS:

```shell
$ export GOPATH:$Home/<user-defined-workspace>/go
Expand Down
50 changes: 23 additions & 27 deletions docs/source/prereqs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -172,50 +172,46 @@ Optional: Install the latest version of [jq](https://stedolan.github.io/jq/downl
<!--- Indent entire section -->
<div style="margin-left: 1.5em;">

### Git
### Docker

Install the latest version of [git](https://git-scm.com/downloads) if it is not already installed.
To use `Fabric binaries`, you will need to have the `uname` command available. You can get it as part of `Git` but beware that only the 64bit version is supported.
Install the latest version of [Docker Desktop](https://docs.docker.com/get-docker/) if it is not already installed.

Update the following `git` configurations
```shell
git config --global core.autocrlf false
git config --global core.longpaths true
```
### WSL2

You can check the setting of these parameters with the following commands:
```shell
git config --get core.autocrlf
git config --get core.longpaths
```
Both the Fabric documentation and Fabric samples rely heavily on a `bash` environment. The recommended
path is to use WSL2 (Windows Subsystem for Linux version 2) to provide a native Linux environment and then you can follow the Linux prerequisites section (excluding the Linux Docker prerequisite as you already have Docker Desktop) and install them into your WSL2 linux distribution.

These need to be false and true respectively.
WSL2 may not be installed by default; you can check and install WSL2 by going into "Programs and Features", clicking on "Turn Windows features on or off" and ensuring that both "Windows Subsystem For Linux" and "Virtual Machine Platform" are selected.

### cURL
Next you will need to install a Linux distribution such as Ubuntu-20.04 and make sure it's set to using version 2 of WSL. Refer to [Install WSL](https://docs.microsoft.com/en-us/windows/wsl/install) for more information.

Install the latest version of [cURL](https://curl.haxx.se/download.html) if it is not already installed.
Finally, you need to ensure Docker Desktop has integration enabled for your distribution so it can interact with Docker elements, such as a bash command window. To do this, open the Docker Desktop gui and go into settings, select `Resources` and them `WSL Integration` and ensure the checkbox for enable integration is checked. You should then see your WSL2 linux distribution listed (if you don't then it is probably because it is still a WSL1 distribution and needs to be converted to WSL2) and you can then toggle the switch to enable integration for that distro. Refer to [Docker Desktop WSL2 backend](https://docs.docker.com/desktop/windows/wsl/) for more information

### Docker
### Microsoft VS Code (Optional)

Install the latest version of [Docker](https://docs.docker.com/get-docker/) if it is not already installed.
Microsoft VS Code provides an IDE that has tight integration with WSL2 Linux Distibutions. Search the Microsoft Marketplace in VS Code for the Remote Development extension pack for more information. This pack includes, among other things, the `Remote - WSL extension` and the `Remote - Containers` extension.

Once installed, confirm the latest versions of both Docker and Docker Compose executables were installed.
### Git For Windows (Optional)

### Go

Optional: Install the latest version of [Go](https://golang.org/doc/install) if it is not already installed
(only required if you will be writing Go chaincode or SDK applications).
Although not required, if you do decide to install Git on Windows and manage the Fabric repositories natively (as opposed to within WSL2 and its Git installation), then make sure you configure Git as follows:

### JQ
Update the following `git` configurations:
```shell
git config --global core.autocrlf false
git config --global core.longpaths true
```

Optional: Install the latest version of [jq](https://stedolan.github.io/jq/download/) if it is not already installed.
(only required for the tutorials related to channel configuration transactions).
You can check the setting of these parameters with the following commands:
```shell
git config --get core.autocrlf
git config --get core.longpaths
```
These output from these commands should be false and true respectively.

</div>

## **Notes**

- The `cURL` command that comes with Git and Docker Toolbox is old and does not handle properly the redirect used in [Getting Started](https://hyperledger-fabric.readthedocs.io/en/latest/getting_started.html). Please make sure you use a newer version from the [cURL downloads page](https://curl.haxx.se/download.html)
- These prerequisites are recommended for Fabric users. If you are a Fabric developer, please refer to the instructions for [Setting up the development environment](https://hyperledger-fabric.readthedocs.io/en/latest/dev-setup/devenv.html).

<!--- Licensed under Creative Commons Attribution 4.0 International License
Expand Down
2 changes: 1 addition & 1 deletion docs/source/tutorial/commercial_paper.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ network.
[buy](#buy-application) and [redeem](#redeem-application) commercial paper

This tutorial has been tested on MacOS and Ubuntu, and should work on other
Linux distributions. A Windows version is under development.
Linux distributions.

## Prerequisites

Expand Down

0 comments on commit 0e9cdb2

Please sign in to comment.