unstick r1872744

Revision 1872744

Date:
2020/01/14 02:06:28
Author:
gjm
Revision Log:
Updates to setup advice
Files:

Legend:

 
Added
 
Removed
 
Modified
  • bloodhound/branches/bh_core_experimental/README.md

     
    1 1 # New Bloodhound
    2 2
    3 ## Requirements
    3 ## Getting the Bloodhound Code:
    4 4
    5 ### Python
    5 There is a reasonable chance that you are reading these instructions from a
    6 copy of the source code that you have already placed on the computer that you
    7 wish to install on. If this is the case you can skip on to the next section.
    6 8
    7 Bloodhound core is currently written in Python3. It should be possible to
    8 install and run the core successfully with Python 3.6 or newer. You may
    9 find that versions from Python 3.4 work but this is not currently tested
    10 and it is possible that Python features from newer versions may sneak in.
    9 While in early development, the alternatives for getting the code include
    10 checking out from [Subversion] with the following command:
    11 11
    12 If you do not already have an appropriate version of Python installed, you
    13 may wish to follow instructions for your platform here:
    12 ```
    13 svn checkout https://svn.apache.org/repos/asf/bloodhound/branches/bh_core_experimental/ bloodhound
    14 ```
    14 15
    15 https://docs.python-guide.org/starting/installation/
    16 or cloning with [Git] from the [Apache Bloodhound Github mirror] - the command
    17 below should also check out the appropriate branch:
    16 18
    17 ### Pipenv
    19 ```
    20 git clone --branch bh_core_experimental https://github.com/apache/bloodhound.git
    21 ```
    18 22
    19 Pipenv is used for looking after Python package dependencies and virtual
    20 environment management.
    23 With the commands as specified, both will place the code in the `bloodhound`
    24 directory.
    21 25
    22 If you already have the `pip` program installed already, installation of
    23 pipenv can be as simple as
    26 [Subversion]: https://subversion.apache.org/
    27 [Git]: https://git-scm.com/
    28 [Apache Bloodhound mirror]: https://github.com/apache/bloodhound
    29 [Github]: https://github.com/
    24 30
    25 ```
    26 pip install --user pipenv
    27 ```
    31 ## Installing Python and Pipenv
    28 32
    29 For more information on installing and usage of pipenv, see
    30 https://docs.pipenv.org/.
    33 Bloodhound core is currently written in [Python 3] and uses [Pipenv] for
    34 looking after the python based dependencies.
    31 35
    32 Once pipenv is installed, the final bit of setup ahead of installing the
    33 rest of the project dependencies is to ensure that you have picked out the
    34 appropriate version of Python for your environment. For the same directory
    35 as the `Pipfile` for the project, you should run:
    36 It should be possible to install and run the core successfully with Python 3.6
    37 or newer. You may find that versions from Python 3.4 work but this is not
    38 currently tested and it is possible that Python features from newer versions
    39 may sneak in.
    36 40
    37 ```
    38 pipenv --python 3
    39 ```
    41 The guide at <https://docs.python-guide.org/> gives good instructions for
    42 installing Python on [Linux][Python on Linux], [MacOS][Python on MacOS] and
    43 [Windows][Python on Windows].
    40 44
    41 If you have multiple versions of Python 3 installed, you may need to be
    42 more specific about the version.
    45 Further information about pipenv is available at <https://docs.pipenv.org/>.
    43 46
    44 ### Pipfile Specified Requirements
    47 [Python 3]: https://docs.python.org/3/
    48 [Pipenv]: https://pipenv.readthedocs.io/en/latest/
    49 [Python on Linux]: https://docs.python-guide.org/starting/install3/linux/#install3-linux
    50 [Python on MacOS]: https://docs.python-guide.org/starting/install3/osx/#install3-osx
    51 [Python on Windows]: https://docs.python-guide.org/starting/install3/win/#install3-windows
    45 52
    46 With pipenv installed and the Python version selected, the rest of the
    47 Python based requrements can be installed with the following command from
    48 the same director as the `Pipfile` for the project:
    53 ## Preparing the Python environment
    49 54
    50 ```
    51 pipenv install
    52 ```
    55 It should now be possible to use pipenv to install the rest of the project
    56 dependencies and bloodhound itself. Note that the exactly required command may
    57 depend on details like whether you have multiple versions of python available
    58 but for most cases, the following should work. If in doubt, just be more
    59 specific about the python version that you intend to use.
    53 60
    54 Additionally, to run tests described later, you should install the
    55 development dependencies:
    61 For the same directory as the `Pipfile` for the project run:
    56 62
    57 63 ```
    58 pipenv install --dev
    64 pipenv --python 3 install
    59 65 ```
    60 66
    61 67 ## Setup
     
    104 110 Unit tests are currently being written with the standard unittest framework.
    105 111 This may be replaced with pytest.
    106 112
    107 The tests may be run with the following command:
    113 Running the tests require a little extra setup:
    108 114
    109 115 ```
    110 pipenv run python manage.py test
    116 pipenv install --dev
    111 117 ```
    112 118
    113 Fixtures for tests when required can be generated with:
    119 after which the tests may be run with the following command:
    114 120
    115 121 ```
    116 pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml
    122 pipenv run python manage.py test
    117 123 ```
    118 124
    119 125 ## Integration Tests
    120 126
    121 Selenium tests currently require that Firefox is installed and `geckodriver` is
    122 also on the path. One way to do this is (example for 64bit linux distributions):
    123
    127 The [Selenium] tests currently require that Firefox is installed and
    128 [geckodriver] is also on the path. If you
    124 129 ```
    130 PLATFORM_EXT="linux64.tar.gz"
    125 131 BIN_LOCATION="$HOME/.local/bin"
    126 PLATFORM_EXT="linux64.tar.gz"
    127 TMP_DIR=/tmp
    132 TMP_DIR=/tmp/geckodriver_download
    133 mkdir -p "$BIN_LOCATION" "$TMP_DIR"
    134
    128 135 LATEST=$(wget -O - https://github.com/mozilla/geckodriver/releases/latest 2>&1 | awk 'match($0, /geckodriver-(v.*)-'"$PLATFORM_EXT"'/, a) {print a[1]; exit}')
    129 136 wget -N -P "$TMP_DIR" "https://github.com/mozilla/geckodriver/releases/download/$LATEST/geckodriver-$LATEST-$PLATFORM_EXT"
    130 137 tar -x geckodriver -zf "$TMP_DIR/geckodriver-$LATEST-$PLATFORM_EXT" -O > "$BIN_LOCATION"/geckodriver
     
    140 147
    141 148 There are currently not many tests - those that are there are in place to test
    142 149 the setup above and assume that there will be useful tests in due course.
    150
    151 [Selenium]: https://selenium.dev/
    152 [geckodriver]: https://firefox-source-docs.mozilla.org/testing/geckodriver/
    153
    154 ## Development notes:
    155
    156 Fixtures for tests when required can be generated with:
    157
    158 ```
    159 pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml
    160 ```