SConsider 0.3.21

// If you are reading this in plaintext or on PyPi, checkout the rendered version
// at https://gitlab.dev.ifs.hsr.ch/ifs/sconsider/blob/master/README.adoc
== SConsider

https://gitlab.dev.ifs.hsr.ch/ifs/sconsider[SConsider] is a https://scons.org[SCons] extension to provide a recursive target detection and dependency handling mechanism.

Instead of manually tracking locations of dependent projects and files, https://gitlab.dev.ifs.hsr.ch/ifs/sconsider[SConsider] will scan your directory tree for `*.sconsider` files and interpret the setting for building up the _package_ and it’s _targets_ during a later phase.
To reference a _target_ from another _package_, you can simply reference it like `SomePackage.TargetA`.

=== Install the development version into your virtualenv

Please check the https://packaging.python.org/distributing/#working-in-development-mode[packaging] information to learn more about this topic.

==== Install

The following command installs a development version into the current virtualenv: `pip install --editable .`
If you want to omit installing dependencies, add `--no-deps` to the command.

Alternatively you can use the _old style_ command: `python setup.py develop`

==== Uninstall

To uninstall a previously installed editable version use: `pip uninstall sconsider`

In case you used the _old style_ command, you need to use the following command: `python setup.py develop --uninstall`

=== Running tests

I recommend using http://tox.testrun.org/[tox] to execute the tests as it properly sets up the right environment.
To see a list of available test environment to execute, list them using `tox -l` and either

* run the default environment(s) `tox`
* run a specific environment `tox -e some-env`

=== Create a source/wheel package

The http://python-packaging-user-guide.readthedocs.org/en/latest/tutorial.html[packaging guide] will show you how to deploy a package and a short http://wheel.readthedocs.org/en/latest[guide on wheels] will explain you what wheels are.

Creating a wheel package is also handled by http://tox.testrun.org/[tox] and the corresponding environment is `wheel`.
It will create the wheel package and if you additionally want to get a source tarball, you can add `sdist` as argument to tox like: `tox -e wheel sdist`

=== (Test-) Upload to pypi

A specific http://tox.testrun.org/[tox] environment `upload` exists in link:tox.ini#L96[tox.ini] which can be used to either https://test.pypi.org/legacy/[test upload] the package or to finally upload it to https://pypi.org/pypi[pypi].
More on this can be found https://mail.python.org/pipermail/distutils-sig/2017-June/030766.html[in this thread] and in the https://packaging.python.org/guides/using-testpypi/#using-t[python packaging docu].

In order to run this environment, a `~/.pypirc` containing at least the following sections must exist and you need to register on both sites:

[source,ini]
----
[distutils]
index-servers =
  pypi
  testpypi
[pypi]
#recommended to leave default
#repository:https://pypi.org/pypi
username:MyPypiUserName
password:MyPypiPass
[testpypi]
repository:https://test.pypi.org/legacy/
username:MyTestpypiUserName
password:MyTestpypiPass
----

Issue the following command to test the package, `testpypi` is the default upload location:

 tox -e upload

or use the following to finally upload it to https://pypi.org/pypi[pypi]:

 PYPI_REPO_NAME=pypi tox -e upload

To use a different https://pypi.org/pypi[pypi] `rc` file, use `PYPIRC_LOCATION=/path/to/pypirc` prefix to the previous commands.

=== Overview of available `setup.py` commands

To get an overview of available commands use:

 python setup.py --help-commands

Help regarding a specific command can be retrieved using:

 python setup.py <command> --help