Author: gjm Date: Tue Jan 14 02:06:28 2020 New Revision: 1872744 URL: http://svn.apache.org/viewvc?rev=1872744&view=rev Log: Updates to setup advice
Modified: bloodhound/branches/bh_core_experimental/README.md Modified: bloodhound/branches/bh_core_experimental/README.md URL: http://svn.apache.org/viewvc/bloodhound/branches/bh_core_experimental/README.md?rev=1872744&r1=1872743&r2=1872744&view=diff ============================================================================== --- bloodhound/branches/bh_core_experimental/README.md (original) +++ bloodhound/branches/bh_core_experimental/README.md Tue Jan 14 02:06:28 2020 @@ -1,61 +1,67 @@ # New Bloodhound -## Requirements +## Getting the Bloodhound Code: -### Python +There is a reasonable chance that you are reading these instructions from a +copy of the source code that you have already placed on the computer that you +wish to install on. If this is the case you can skip on to the next section. -Bloodhound core is currently written in Python3. It should be possible to -install and run the core successfully with Python 3.6 or newer. You may -find that versions from Python 3.4 work but this is not currently tested -and it is possible that Python features from newer versions may sneak in. +While in early development, the alternatives for getting the code include +checking out from [Subversion] with the following command: -If you do not already have an appropriate version of Python installed, you -may wish to follow instructions for your platform here: +``` +svn checkout https://svn.apache.org/repos/asf/bloodhound/branches/bh_core_experimental/ bloodhound +``` - https://docs.python-guide.org/starting/installation/ +or cloning with [Git] from the [Apache Bloodhound Github mirror] - the command +below should also check out the appropriate branch: -### Pipenv +``` +git clone --branch bh_core_experimental https://github.com/apache/bloodhound.git +``` -Pipenv is used for looking after Python package dependencies and virtual -environment management. +With the commands as specified, both will place the code in the `bloodhound` +directory. -If you already have the `pip` program installed already, installation of -pipenv can be as simple as +[Subversion]: https://subversion.apache.org/ +[Git]: https://git-scm.com/ +[Apache Bloodhound mirror]: https://github.com/apache/bloodhound +[Github]: https://github.com/ -``` -pip install --user pipenv -``` +## Installing Python and Pipenv -For more information on installing and usage of pipenv, see -https://docs.pipenv.org/. +Bloodhound core is currently written in [Python 3] and uses [Pipenv] for +looking after the python based dependencies. -Once pipenv is installed, the final bit of setup ahead of installing the -rest of the project dependencies is to ensure that you have picked out the -appropriate version of Python for your environment. For the same directory -as the `Pipfile` for the project, you should run: +It should be possible to install and run the core successfully with Python 3.6 +or newer. You may find that versions from Python 3.4 work but this is not +currently tested and it is possible that Python features from newer versions +may sneak in. -``` -pipenv --python 3 -``` +The guide at <https://docs.python-guide.org/> gives good instructions for +installing Python on [Linux][Python on Linux], [MacOS][Python on MacOS] and +[Windows][Python on Windows]. -If you have multiple versions of Python 3 installed, you may need to be -more specific about the version. +Further information about pipenv is available at <https://docs.pipenv.org/>. -### Pipfile Specified Requirements +[Python 3]: https://docs.python.org/3/ +[Pipenv]: https://pipenv.readthedocs.io/en/latest/ +[Python on Linux]: https://docs.python-guide.org/starting/install3/linux/#install3-linux +[Python on MacOS]: https://docs.python-guide.org/starting/install3/osx/#install3-osx +[Python on Windows]: https://docs.python-guide.org/starting/install3/win/#install3-windows -With pipenv installed and the Python version selected, the rest of the -Python based requrements can be installed with the following command from -the same director as the `Pipfile` for the project: +## Preparing the Python environment -``` -pipenv install -``` +It should now be possible to use pipenv to install the rest of the project +dependencies and bloodhound itself. Note that the exactly required command may +depend on details like whether you have multiple versions of python available +but for most cases, the following should work. If in doubt, just be more +specific about the python version that you intend to use. -Additionally, to run tests described later, you should install the -development dependencies: +For the same directory as the `Pipfile` for the project run: ``` -pipenv install --dev +pipenv --python 3 install ``` ## Setup @@ -104,27 +110,28 @@ These paths are subject to change. Unit tests are currently being written with the standard unittest framework. This may be replaced with pytest. -The tests may be run with the following command: +Running the tests require a little extra setup: ``` -pipenv run python manage.py test +pipenv install --dev ``` -Fixtures for tests when required can be generated with: +after which the tests may be run with the following command: ``` -pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml +pipenv run python manage.py test ``` ## Integration Tests -Selenium tests currently require that Firefox is installed and `geckodriver` is -also on the path. One way to do this is (example for 64bit linux distributions): - +The [Selenium] tests currently require that Firefox is installed and +[geckodriver] is also on the path. If you ``` -BIN_LOCATION="$HOME/.local/bin" PLATFORM_EXT="linux64.tar.gz" -TMP_DIR=/tmp +BIN_LOCATION="$HOME/.local/bin" +TMP_DIR=/tmp/geckodriver_download +mkdir -p "$BIN_LOCATION" "$TMP_DIR" + LATEST=$(wget -O - https://github.com/mozilla/geckodriver/releases/latest 2>&1 | awk 'match($0, /geckodriver-(v.*)-'"$PLATFORM_EXT"'/, a) {print a[1]; exit}') wget -N -P "$TMP_DIR" "https://github.com/mozilla/geckodriver/releases/download/$LATEST/geckodriver-$LATEST-$PLATFORM_EXT" tar -x geckodriver -zf "$TMP_DIR/geckodriver-$LATEST-$PLATFORM_EXT" -O > "$BIN_LOCATION"/geckodriver @@ -140,3 +147,14 @@ pipenv run python functional_tests.py There are currently not many tests - those that are there are in place to test the setup above and assume that there will be useful tests in due course. + +[Selenium]: https://selenium.dev/ +[geckodriver]: https://firefox-source-docs.mozilla.org/testing/geckodriver/ + +## Development notes: + +Fixtures for tests when required can be generated with: + +``` +pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml +```