As mentioned, I was messing around with the instructions last night and so this is the patch that went in on that basis.
Included there is a bit of updated advice for ways to get the code - the methods may not really be best practice but I was aiming for conciseness and consistency between the svn and github routes. You can look here for the current state on the branch: http://svn.apache.org/viewvc/bloodhound/branches/bh_core_experimental/README.md?view=markup Some people may prefer the equivalent on github for a prettier view: https://github.com/apache/bloodhound/blob/bh_core_experimental/README.md If anyone can spot better instructions for selenium installation, then that could be useful as it would save my temptation to write a python script for downloading and installing in a cross platform fashion that I may find difficult to test! Cheers! On Tue, 14 Jan 2020, at 2:06 AM, [email protected] wrote: > 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 > +``` > > > -- Cheers, Gary
