Cuppa
=====
A simple, extensible build system for use with
`Scons <http://www.scons.org/>`__. **Cuppa** is designed to leverage the
capabilities of Scons, while allowing developers to focus on the task of
describing what needs to be built. In general **cuppa** supports
``make`` like usage on the command-line. That is developers can simply
write:
.. code:: sh
scons -D
and have Scons "do the right thing"; building targets for any
``sconscript`` files found in the current directory.
**Cuppa** can be installed as a normal python package or installed
locally into a ``site_scons`` directory allowing it to be effortlessly
integrated into any Scons setup.
Note: ``-D`` tells ``scons`` to look for an ``sconstruct`` file in
the current or in parent directories and if it finds one execute the
``sconscript`` files as if called from that directory. This ensures
everything works as expected. For more details refer to the `Scons
documentation <http://www.scons.org/documentation.php>`__
Quick Intro
-----------
Get **cuppa**
~~~~~~~~~~~~~
The simpest way to get **cuppa** is to ``pip install`` it using:
::
pip install cuppa
Sample ``sconstruct`` file
~~~~~~~~~~~~~~~~~~~~~~~~~~
Let's look at a minimal ``sconstruct`` that makes use of **cuppa**. It
could look like this:
.. code:: python
# Pull in all the Cuppa goodies..
import cuppa
# Call sconscripts to do the work
cuppa.run()
Calling the ``run`` method in the ``cuppa`` module starts the build
process calling ``sconscript`` files.
Sample ``sconscript`` file
~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is an example ``sconscript`` file that builds all \*.cpp files in
the directory where it resides:
.. code:: python
Import( 'env' )
# Build all *.cpp source files as executables
for Source in env.GlobFiles('*.cpp'):
env.Build( Source[:-4], Source )
The ``env.Build()`` method is provided by **cuppa** and does essentially
what ``env.Program()`` does but in addition is both toolchain and
variant aware, and further can provide notifications on progress.
Note: Source[:-4] simply strips off the file extension ``.cpp``,
that is, the last 4 characters of the file name.
If our ``sconscript`` file was for a directory containing \*.cpp files
that are actually tests then we could instead write the ``sconscript``
file as:
.. code:: python
Import( 'env' )
# Build all *.cpp source files as executables to be run as tests
for Source in env.GlobFiles('*.cpp'):
env.BuildTest( Source[:-4], Source )
The ``env.BuildTest()`` method is provided by **cuppa** and builds the
sources specified as ``env.Build()`` does.
However, in addition, passing ``--test`` on the command-line will also
result in the executable produced being run by a **runner**. The default
test runner simply treats each executable as a test case and each
directory or executables as a test suite. If the process executes
cleanly the test passed, if not it failed.
To run this on the command-line we would write:
.. code:: sh
scons -D --test
If we only want to build and test *debug* executables we can instead
write this:
.. code:: sh
scons -D --dbg --test
Or for release only pass ``--rel``.
**cuppa** also makes it easy to work with dependencies. For example, if
`boost <http://www.boost.org/>`__ was a default dependency for all your
``sconscript`` files you could write your sconstruct file as follows:
.. code:: python
import cuppa
cuppa.run(
default_options = {
'boost-home': '<Location of Boost>'
},
default_dependencies = [
'boost'
]
)
This will automatically ensure that necessary includes and other compile
options are set for the boost version that is found at ``boost-home``.
If you need to link against specific boost libraries this can also be
done in the sconscript file as follows:
.. code:: python
Import('env')
Test = 'my_complex_test'
Sources = [
Test + '.cpp'
]
env.AppendUnique( STATICLIBS = [
env.BoostStaticLibrary( 'system' ),
env.BoostStaticLibrary( 'log' ),
env.BoostStaticLibrary( 'thread' ),
env.BoostStaticLibrary( 'timer' ),
env.BoostStaticLibrary( 'chrono' ),
env.BoostStaticLibrary( 'filesystem' ),
] )
env.BuildTest( Test, Sources )
The ``BoostStaticLibrary()`` method ensures that the library is built in
the correct build variant as required. If you preferred to use dynamic
linking then that can also be achieved using ``BoostSharedLibrary()``.
The point is the complexities of using `boost <http://www.boost.org/>`__
as a dependency are encapsulated and managed separately from the
scontruct and sconscript files allowing developers to focus on intent
not method.
Design Principles
-----------------
**cuppa** has been written primarily to provide a clean and structured
way to leverage the power of Scons without the usual problems of hugely
complex ``scontruct`` files that diverge between projects. Key goals of
**cuppa** are:
- minimise the need for adding logic into ``sconscript`` files, keeping
them as declarative as possible.
- allow declarative ``sconscript``\ s that are both much clearer and
significantly simpler than the equivalent ``make`` file, without the
need to learn a whole new scripting language like ``make`` or
``cmake``.
- provide a clear structure for extending the facilities offered by
**cuppa**
- provide a clear vocabulary for building projects
- codify Scons best practices into **cuppa** itself so that users just
need to call appropriate methods knowing that **cuppa** will do the
right thing with their intent
- provide a framework that allows experts to focus on providing
facilities for others to use. Write once, use everywhere. For example
one person who knows how best to make
`boost <http://www.boost.org/>`__ available as a dependency can
manage that dependency and allow others to use it seamlessly.
More Details
------------
For more details refer to the `project homepage <https://github.com/ja11sop/cuppa>`__.
Acknowledgements
----------------
This work is based on the build system used in
`clearpool.io <http://www.clearpool.io>`__ during development of its
next generation exchange platform.
Raw data
{
"_id": null,
"home_page": "https://github.com/ja11sop/cuppa",
"name": "cuppa",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "scons,build,c++",
"author": "ja11sop",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b8/d3/7a5f76ead42070f9af93a18c9da1615b0ba987eeaa667f277a2c38549a43/cuppa-0.9.120.tar.gz",
"platform": null,
"description": "Cuppa\n=====\n\nA simple, extensible build system for use with\n`Scons <http://www.scons.org/>`__. **Cuppa** is designed to leverage the\ncapabilities of Scons, while allowing developers to focus on the task of\ndescribing what needs to be built. In general **cuppa** supports\n``make`` like usage on the command-line. That is developers can simply\nwrite:\n\n.. code:: sh\n\n scons -D\n\nand have Scons \"do the right thing\"; building targets for any\n``sconscript`` files found in the current directory.\n\n**Cuppa** can be installed as a normal python package or installed\nlocally into a ``site_scons`` directory allowing it to be effortlessly\nintegrated into any Scons setup.\n\n Note: ``-D`` tells ``scons`` to look for an ``sconstruct`` file in\n the current or in parent directories and if it finds one execute the\n ``sconscript`` files as if called from that directory. This ensures\n everything works as expected. For more details refer to the `Scons\n documentation <http://www.scons.org/documentation.php>`__\n\n\nQuick Intro\n-----------\n\nGet **cuppa**\n~~~~~~~~~~~~~\n\nThe simpest way to get **cuppa** is to ``pip install`` it using:\n\n::\n\n pip install cuppa\n\n\nSample ``sconstruct`` file\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nLet's look at a minimal ``sconstruct`` that makes use of **cuppa**. It\ncould look like this:\n\n.. code:: python\n\n # Pull in all the Cuppa goodies..\n import cuppa\n\n # Call sconscripts to do the work\n cuppa.run()\n\nCalling the ``run`` method in the ``cuppa`` module starts the build\nprocess calling ``sconscript`` files.\n\nSample ``sconscript`` file\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nHere is an example ``sconscript`` file that builds all \\*.cpp files in\nthe directory where it resides:\n\n.. code:: python\n\n Import( 'env' )\n\n # Build all *.cpp source files as executables\n for Source in env.GlobFiles('*.cpp'):\n env.Build( Source[:-4], Source )\n\nThe ``env.Build()`` method is provided by **cuppa** and does essentially\nwhat ``env.Program()`` does but in addition is both toolchain and\nvariant aware, and further can provide notifications on progress.\n\n Note: Source[:-4] simply strips off the file extension ``.cpp``,\n that is, the last 4 characters of the file name.\n\nIf our ``sconscript`` file was for a directory containing \\*.cpp files\nthat are actually tests then we could instead write the ``sconscript``\nfile as:\n\n.. code:: python\n\n Import( 'env' )\n\n # Build all *.cpp source files as executables to be run as tests\n for Source in env.GlobFiles('*.cpp'):\n env.BuildTest( Source[:-4], Source )\n\nThe ``env.BuildTest()`` method is provided by **cuppa** and builds the\nsources specified as ``env.Build()`` does.\n\nHowever, in addition, passing ``--test`` on the command-line will also\nresult in the executable produced being run by a **runner**. The default\ntest runner simply treats each executable as a test case and each\ndirectory or executables as a test suite. If the process executes\ncleanly the test passed, if not it failed.\n\nTo run this on the command-line we would write:\n\n.. code:: sh\n\n scons -D --test\n\nIf we only want to build and test *debug* executables we can instead\nwrite this:\n\n.. code:: sh\n\n scons -D --dbg --test\n\nOr for release only pass ``--rel``.\n\n**cuppa** also makes it easy to work with dependencies. For example, if\n`boost <http://www.boost.org/>`__ was a default dependency for all your\n``sconscript`` files you could write your sconstruct file as follows:\n\n.. code:: python\n\n import cuppa\n\n cuppa.run(\n default_options = {\n 'boost-home': '<Location of Boost>'\n },\n default_dependencies = [\n 'boost'\n ]\n )\n\nThis will automatically ensure that necessary includes and other compile\noptions are set for the boost version that is found at ``boost-home``.\nIf you need to link against specific boost libraries this can also be\ndone in the sconscript file as follows:\n\n.. code:: python\n\n Import('env')\n\n Test = 'my_complex_test'\n\n Sources = [\n Test + '.cpp'\n ]\n\n env.AppendUnique( STATICLIBS = [\n env.BoostStaticLibrary( 'system' ),\n env.BoostStaticLibrary( 'log' ),\n env.BoostStaticLibrary( 'thread' ),\n env.BoostStaticLibrary( 'timer' ),\n env.BoostStaticLibrary( 'chrono' ),\n env.BoostStaticLibrary( 'filesystem' ),\n ] )\n\n env.BuildTest( Test, Sources )\n\nThe ``BoostStaticLibrary()`` method ensures that the library is built in\nthe correct build variant as required. If you preferred to use dynamic\nlinking then that can also be achieved using ``BoostSharedLibrary()``.\n\nThe point is the complexities of using `boost <http://www.boost.org/>`__\nas a dependency are encapsulated and managed separately from the\nscontruct and sconscript files allowing developers to focus on intent\nnot method.\n\nDesign Principles\n-----------------\n\n**cuppa** has been written primarily to provide a clean and structured\nway to leverage the power of Scons without the usual problems of hugely\ncomplex ``scontruct`` files that diverge between projects. Key goals of\n**cuppa** are:\n\n- minimise the need for adding logic into ``sconscript`` files, keeping\n them as declarative as possible.\n- allow declarative ``sconscript``\\ s that are both much clearer and\n significantly simpler than the equivalent ``make`` file, without the\n need to learn a whole new scripting language like ``make`` or\n ``cmake``.\n- provide a clear structure for extending the facilities offered by\n **cuppa**\n- provide a clear vocabulary for building projects\n- codify Scons best practices into **cuppa** itself so that users just\n need to call appropriate methods knowing that **cuppa** will do the\n right thing with their intent\n- provide a framework that allows experts to focus on providing\n facilities for others to use. Write once, use everywhere. For example\n one person who knows how best to make\n `boost <http://www.boost.org/>`__ available as a dependency can\n manage that dependency and allow others to use it seamlessly.\n\nMore Details\n------------\n\nFor more details refer to the `project homepage <https://github.com/ja11sop/cuppa>`__.\n\nAcknowledgements\n----------------\n\nThis work is based on the build system used in\n`clearpool.io <http://www.clearpool.io>`__ during development of its\nnext generation exchange platform.\n",
"bugtrack_url": null,
"license": "Boost Software License 1.0 - http://www.boost.org/LICENSE_1_0.txt",
"summary": "Cuppa, an extension package to simplify and extend Scons",
"version": "0.9.120",
"project_urls": {
"Homepage": "https://github.com/ja11sop/cuppa"
},
"split_keywords": [
"scons",
"build",
"c++"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "796c70d3513cad468797f82818d13bebb35774dce721efe99219f45fd039635e",
"md5": "e2116ac1502a5b6393134174215a61c2",
"sha256": "bbdde8632dc7f3a3921bf2bed1fafdcd2b5526188c4fdbb2abe7573d7f4f2d5c"
},
"downloads": -1,
"filename": "cuppa-0.9.120-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2116ac1502a5b6393134174215a61c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 219690,
"upload_time": "2024-02-05T21:40:38",
"upload_time_iso_8601": "2024-02-05T21:40:38.136076Z",
"url": "https://files.pythonhosted.org/packages/79/6c/70d3513cad468797f82818d13bebb35774dce721efe99219f45fd039635e/cuppa-0.9.120-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b8d37a5f76ead42070f9af93a18c9da1615b0ba987eeaa667f277a2c38549a43",
"md5": "a58fc092699a58a0755ad3161e65663d",
"sha256": "448e92ea471bac8419df598fa672c4bd7f5b5c70172f89acec9c1ef77b9249c9"
},
"downloads": -1,
"filename": "cuppa-0.9.120.tar.gz",
"has_sig": false,
"md5_digest": "a58fc092699a58a0755ad3161e65663d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 173042,
"upload_time": "2024-02-05T21:40:41",
"upload_time_iso_8601": "2024-02-05T21:40:41.322564Z",
"url": "https://files.pythonhosted.org/packages/b8/d3/7a5f76ead42070f9af93a18c9da1615b0ba987eeaa667f277a2c38549a43/cuppa-0.9.120.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-05 21:40:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ja11sop",
"github_project": "cuppa",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cuppa"
}
JSON
