From dfb7cf48887158ffb93fc483b0c8effe79b5fdb2 Mon Sep 17 00:00:00 2001
From: Ana Maria Martinez Gomez <anamaria.martinezgom@mandiant.com>
Date: Mon, 15 Mar 2021 19:42:57 +0100
Subject: [PATCH] py3: set and document env

Document how to use env now that we are Python3 only. Adapt
`scripts/ci.sh`.
---
 doc/installation.md | 43 +++++++++++++++++++++++++++++++------------
 scripts/ci.sh       | 16 ++++------------
 2 files changed, 35 insertions(+), 24 deletions(-)

diff --git a/doc/installation.md b/doc/installation.md
index 6bc7ab55..bc7a509d 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -59,6 +59,25 @@ Use `pip` to install the source code in "editable" mode. This means that Python
 
 You'll find that the `capa.exe` (Windows) or `capa` (Linux/MacOS) executables in your path now invoke the capa binary from this directory.
 
+#### Development
+
+##### venv [optional]
+
+For development, we recommend to use [venv](https://docs.python.org/3/tutorial/venv.html). It allows you to create a virtual environment: a self-contained directory tree that contains a Python installation for a particular version of Python, plus a number of additional packages. This approach avoids conflicts between the requirements of different applications on your computer. It also ensures that you don't overlook to add a new requirement to `setup.up` using a library already installed on your system.
+
+To create an environment (in the parent directory, to avoid commiting it by accident or messing with the linters), run:
+`$ python3 -m venv ../capa-env`
+
+To activate `capa-env` in Linux or MacOS, run:
+`$ source ../capa-env/bin/activate`
+
+To activate `capa-env` in Windows, run:
+`$ ..\capa-env\Scripts\activate.bat`
+
+For more details about creating and using virtual environments, check out the [venv documentation](https://docs.python.org/3/tutorial/venv.html).
+
+##### Install development dependencies
+
 We use the following tools to ensure consistent code style and formatting:
   - [black](https://github.com/psf/black) code formatter, with `-l 120`
   - [isort 5](https://pypi.org/project/isort/) code formatter, with `--profile black --length-sort --line-width 120`
@@ -69,11 +88,21 @@ To install these development dependencies, run:
 
 `$ pip install -e /local/path/to/src[dev]`
 
-Note that some development dependencies (including the black code formatter) require Python 3.
-
 To check the code style, formatting and run the tests you can run the script `scripts/ci.sh`.
 You can run it with the argument `no_tests` to skip the tests and only run the code style and formatting: `scripts/ci.sh no_tests`
 
+##### Setup hooks [optional]
+
+If you plan to contribute to capa, you may want to setup the hooks.
+Run `scripts/setup-hooks.sh` to set the following hooks up:
+- The `pre-commit` hook runs checks before every `git commit`.
+  It runs `scripts/ci.sh no_tests` aborting the commit if there are code style or rule linter offenses you need to fix.
+- The `pre-push` hook runs checks before every `git push`.
+  It runs `scripts/ci.sh` aborting the push if there are code style or rule linter offenses or if the tests fail.
+  This way you can ensure everything is alright before sending a pull request.
+
+You can skip the checks by using the `--no-verify` git option.
+
 ### 3. Compile binary using PyInstaller
 We compile capa standalone binaries using PyInstaller. To reproduce the build process check out the source code as described above and follow these steps.
 
@@ -86,13 +115,3 @@ For Python 3: `$ pip install 'pyinstaller`
 `$ pyinstaller .github/pyinstaller/pyinstaller.spec`
 
 You can find the compiled binary in the created directory `dist/`.
-
-### 4. Setup hooks [optional]
-If you plan to contribute to capa, you may want to setup the hooks.
-Run `scripts/setup-hooks.sh` to set the following hooks up:
-- The `pre-commit` hook runs checks before every `git commit`.
-  It runs `scripts/ci.sh no_tests` aborting the commit if there are code style or rule linter offenses you need to fix.
-  You can skip this check by using the `--no-verify` git option.
-- The `pre-push` hook runs checks before every `git push`.
-  It runs `scripts/ci.sh` aborting the push if there are code style or rule linter offenses or if the tests fail.
-  This way you can ensure everything is alright before sending a pull request.
diff --git a/scripts/ci.sh b/scripts/ci.sh
index f9b0bde1..204bf266 100755
--- a/scripts/ci.sh
+++ b/scripts/ci.sh
@@ -9,6 +9,7 @@
 # See the License for the specific language governing permissions and limitations under the License.
 
 # Use a console with emojis support for a better experience
+# Use venv to ensure that `python` calls the correct python version
 
 # Stash uncommited changes
 MSG="pre-push-$(date +%s)";
@@ -25,17 +26,8 @@ restore_stashed() {
   fi
 }
 
-python_3() {
-  case "$(uname -s)" in
-   CYGWIN*|MINGW32*|MSYS*|MINGW*)
-     py -3 -m $1 > $2 2>&1;;
-   *)
-     python3 -m $1 > $2 2>&1;;
-  esac
-}
-
 # Run isort and print state
-python_3 'isort --profile black --length-sort --line-width 120 -c .' 'isort-output.log';
+python -m isort --profile black --length-sort --line-width 120 -c . > isort-output.log 2>&1;
 if [ $? == 0 ]; then
   echo 'isort succeeded!! 💖';
 else
@@ -46,7 +38,7 @@ else
 fi
 
 # Run black and print state
-python_3 'black -l 120 --check .' 'black-output.log';
+python -m black -l 120 --check . > black-output.log 2>&1;
 if [ $? == 0 ]; then
   echo 'black succeeded!! 💝';
 else
@@ -70,7 +62,7 @@ fi
 # Run tests except if first argument is no_tests
 if [ "$1" != 'no_tests' ]; then
   echo 'Running tests, please wait ⌛';
-  pytest tests/ --maxfail=1;
+  python -m pytest tests/ --maxfail=1;
   if [ $? == 0 ]; then
     echo 'Tests succeed!! 🎉';
   else