Skip to content

Commit 85e10b0

Browse files
jrmadsenjrmadsen
committed
Updated docs
1 parent 0e7ee47 commit 85e10b0

File tree

4 files changed

+140
-89
lines changed

4 files changed

+140
-89
lines changed

‎docs/about.rst

+79-61
Original file line numberDiff line numberDiff line change
@@ -47,26 +47,23 @@ extension that uses ``nosetests`` for unit-testing:
4747
4848
#!/usr/bin/env python
4949
50-
import os, sys, platform
50+
import os
51+
import sys
52+
import platform
5153
import pyctest.pyctest as pyctest
5254
import pyctest.helpers as helpers
5355
54-
parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(), binary_dir=os.getcwd())
55-
parser.add_argument("-n", "--build", type=str, required=True, help="Build name for identification")
56+
parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(),binary_dir=os.getcwd(), vcs_type="git")
5657
args = parser.parse_args()
5758
5859
pyctest.BUILD_NAME = "{}".format(args.build)
5960
pyctest.BUILD_COMMAND = "python setup.py build_ext --inplace"
60-
pyctest.UPDATE_COMMAND = "git"
6161
6262
test = pyctest.test()
6363
test.SetName("unittest")
64-
# insert the command to run the tests for project
6564
test.SetCommand(["nosetests"])
6665
67-
pyctest.generate_config()
68-
pyctest.generate_test_file()
69-
pyctest.run(pyctest.ARGUMENTS)
66+
pyctest.run()
7067
7168
Example for autotools project
7269
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -75,12 +72,15 @@ Example for autotools project
7572
7673
#!/usr/bin/env python
7774
78-
import os, sys, platform
75+
import os
76+
import sys
77+
import platform
7978
import multiprocessing as mp
8079
import pyctest.pyctest as pyctest
8180
import pyctest.helpers as helpers
8281
83-
parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(), binary_dir=os.getcwd())
82+
parser = helpers.ArgumentParser("ProjectName", source_dir=os.getcwd(), binary_dir=os.getcwd(),
83+
vcs_type="git")
8484
parser.add_argument("-n", "--build", type=str, required=True, help="Build name for identification")
8585
args = parser.parse_args()
8686
@@ -91,18 +91,13 @@ Example for autotools project
9191
cmd.Execute()
9292
9393
pyctest.BUILD_NAME = "{}".format(args.build)
94-
pyctest.UPDATE_COMMAND = "git"
9594
pyctest.CONFIGURE_COMMAND = "./configure"
9695
pyctest.BUILD_COMMAND = "make -j{}".format(mp.cpu_count())
9796
98-
test = pyctest.test()
99-
test.SetName("unittest")
100-
# insert the command to run the tests for project
101-
test.SetCommand(["./run-testing.sh"])
97+
# alternate test declaration format
98+
pyctest.test("unittest", ["./run-testing.sh"])
10299
103-
pyctest.generate_config()
104-
pyctest.generate_test_file()
105-
pyctest.run(pyctest.ARGUMENTS)
100+
pyctest.run()
106101
107102
Example for CMake project
108103
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -118,24 +113,21 @@ Example for CMake project
118113
import pyctest.pyctest as pyctest
119114
import pyctest.helpers as helpers
120115
121-
binary_dir = os.path.join(os.getcwd(), "build-ProjectName")
116+
project = "PyCTestDemo"
117+
binary_dir = os.path.join(os.getcwd(), "{}-build".format(project))
122118
parser = helpers.ArgumentParser("ProjectName", os.getcwd(), binary_dir)
123119
parser.add_argument("-n", "--build", type=str, required=True, help="Build name for identification")
124120
args = parser.parse_args()
125121
126122
pyctest.BUILD_NAME = "{}".format(args.build)
127123
pyctest.UPDATE_COMMAND = "git"
128124
pyctest.CONFIGURE_COMMAND = "cmake {}".format(pyctest.SOURCE_DIRECTORY)
129-
pyctest.BUILD_COMMAND = "cmake --build {} --target all -- -j{}".format(pyctest.BINARY_DIRECTORY, mp.cpu_count())
125+
pyctest.BUILD_COMMAND = "cmake --build {} --target all -- -j{}".format(
126+
pyctest.BINARY_DIRECTORY, mp.cpu_count())
130127
131-
test = pyctest.test()
132-
test.SetName("unittest")
133-
# insert the command to run the tests for project
134-
test.SetCommand(["./run-testing.sh"])
128+
pyctest.test("unittest", ["./run-testing.sh"])
135129
136-
pyctest.generate_config(pyctest.BINARY_DIRECTORY)
137-
pyctest.generate_test_file(pyctest.BINARY_DIRECTORY)
138-
pyctest.run(pyctest.ARGUMENTS, pyctest.BINARY_DIRECTORY)
130+
pyctest.run()
139131
140132
Python Modules
141133
~~~~~~~~~~~~~~
@@ -155,6 +147,34 @@ Python Modules
155147
- It is possible to call CMake from this package but it is generally
156148
not the purpose
157149

150+
Direct Access to CMake/CTest/CPack Executables
151+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152+
153+
- ``python -m pyctest.cmake <ARGS>`` == ``cmake <ARGS>``
154+
- ``python -m pyctest.ctest <ARGS>`` == ``ctest <ARGS>``
155+
- ``python -m pyctest.cpack <ARGS>`` == ``cpack <ARGS>``
156+
157+
Following Python code:
158+
159+
.. code:: python
160+
161+
from pyctest.ctest import CTest
162+
from pyctest.cmake import CMake
163+
from pyctest.cpack import CPack
164+
165+
CMake({"CMAKE_BUILD_TYPE":"Release"}, os.getcwd(), "-G", "Ninja")
166+
CTest("--build-and-test", os.getcwd(), "-VV")
167+
CPack("-G", "TGZ")
168+
169+
is equivalent to the following shell commands:
170+
171+
.. code:: bash
172+
173+
cmake -DCMAKE_BUILD_TYPE=Release ${PWD} -G Ninja
174+
ctest --build-and-test ${PWD} -VV
175+
cpack -G TGZ
176+
177+
158178
Benefits
159179
~~~~~~~~
160180

@@ -237,10 +257,7 @@ without any configuration, build, etc. steps
237257
238258
import os
239259
import sys
240-
import shutil
241-
import argparse
242260
import platform
243-
import traceback
244261
245262
import pyctest.pyctest as pyctest
246263
import pyctest.pycmake as pycmake
@@ -263,49 +280,50 @@ without any configuration, build, etc. steps
263280
pyctest.MODEL = "Continuous"
264281
pyctest.SITE = platform.node()
265282
266-
# create a Test object
283+
# create a test
267284
test = pyctest.test()
268285
test.SetName("list_directory")
269286
test.SetCommand(["ls", directory])
270287
test.SetProperty("WORKING_DIRECTORY", os.getcwd())
271288
272289
# create a second test
273-
# previous test is already stored by PyCTest
274-
test = pyctest.test()
275-
test.SetName("hostname")
276-
test.SetCommand(["hostname"])
277-
test.SetProperty("TIMEOUT", "10")
278-
279-
# generate the CTestConfig.cmake and CTestCustom.cmake
280-
pyctest.generate_config(directory)
281-
282-
# generate the CTestTestfile.cmake file
283-
pyctest.generate_test_file(directory)
290+
pyctest.test("hostname", ["hostname"], {"TIMEOUT": "10"})
284291
285292
# run CTest -- e.g. ctest -VV ${PWD}/pycm-test
286-
pyctest.run(pyctest.ARGUMENTS, directory)
293+
pyctest.run()
287294
288295
.. code:: bash
289296
297+
#############################################
298+
# ____ _ _ ___ ____ ____ ____ ____ #
299+
# ( _ \( \/ )/ __)(_ _)( __)/ ___)(_ _) #
300+
# ) __/ ) /( (__ )( ) _) \___ \ )( #
301+
# (__) (__/ \___) (__) (____)(____/ (__) #
302+
# #
303+
#############################################
304+
305+
PyCTest args: []
306+
CTest args: []
307+
CMake args: []
290308
CTest arguments (default): '-V -DSTAGES=Start;Update;Configure;Build;Test;Coverage;MemCheck -S Stages.cmake -j1'
291-
Writing CTest test file: "/Users/jrmadsen/devel/c++/pyctest-master/pycm-test/CTestTestfile.cmake"...
309+
Writing CTest test file: "/Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test/CTestTestfile.cmake"...
292310
Generating test "list_directory"...
293311
Generating test "hostname"...
294312
-- STAGES = Start;Update;Configure;Build;Test;Coverage;MemCheck
295-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Running CTEST_START stage...
313+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Running CTEST_START stage...
296314
Run dashboard with model Continuous
297-
Source directory: /Users/jrmadsen/devel/c++/pyctest-master/pycm-test
298-
Build directory: /Users/jrmadsen/devel/c++/pyctest-master/pycm-test
299-
Track: Continuous
300-
Reading ctest configuration file: /Users/jrmadsen/devel/c++/pyctest-master/pycm-test/CTestConfig.cmake
301-
Site: JRM-macOS-DOE.local
302-
Build name: [Darwin macOS 10.13.6 x86_64] [Python 3.6.7]
303-
Use Continuous tag: 20181129-2118
304-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_UPDATE stage...
305-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_CONFIGURE stage...
306-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_BUILD stage...
307-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Running CTEST_TEST stage...
308-
Test project /Users/jrmadsen/devel/c++/pyctest-master/pycm-test
315+
Source directory: /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test
316+
Build directory: /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test
317+
Track: Continuous
318+
Reading ctest configuration file: /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test/CTestConfig.cmake
319+
Site: JRM-macOS-DOE.local.dhcp.lbl.gov
320+
Build name: [Darwin macOS 10.14.2 x86_64] [Python 3.7.0]
321+
Use Continuous tag: 20190116-2239
322+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_UPDATE stage...
323+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_CONFIGURE stage...
324+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_BUILD stage...
325+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Running CTEST_TEST stage...
326+
Test project /Users/jrmadsen/devel/c++/pyctest-master/docs/pycm-test
309327
Start 1: list_directory
310328
1/2 Test #1: list_directory ................... Passed 0.00 sec
311329
Start 2: hostname
@@ -314,8 +332,8 @@ without any configuration, build, etc. steps
314332
100% tests passed, 0 tests failed out of 2
315333
316334
Total Test time (real) = 0.01 sec
317-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_COVERAGE stage...
318-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_MEMCHECK stage...
319-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Skipping CTEST_SUBMIT stage...
320-
-- [[Darwin macOS 10.13.6 x86_64] [Python 3.6.7]] Finished Continuous Stages (Start;Update;Configure;Build;Test;Coverage;MemCheck)
335+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_COVERAGE stage...
336+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_MEMCHECK stage...
337+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Skipping CTEST_SUBMIT stage...
338+
-- [[Darwin macOS 10.14.2 x86_64] [Python 3.7.0]] Finished Continuous Stages (Start;Update;Configure;Build;Test;Coverage;MemCheck)
321339

‎docs/environment.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name: docs
22
channels:
3-
- jrmadsen
43
- conda-forge
4+
- jrmadsen
55
- defaults
66
dependencies:
77
- python=3.7

‎docs/index.rst

+21-5
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,30 @@ Build Status
1919
.. image:: https://ci.appveyor.com/api/projects/status/p7m76ovx7sg781pf/branch/master?svg=true
2020
:target: https://ci.appveyor.com/project/jrmadsen/pyctest/branch/master
2121

22-
########
23-
Anaconda
24-
########
22+
######################
23+
Anaconda (conda-forge)
24+
######################
2525

26-
.. image:: https://anaconda.org/jrmadsen/pyctest/badges/version.svg
26+
.. image:: https://img.shields.io/badge/recipe-pyctest-green.svg
27+
:target: https://anaconda.org/conda-forge/pyctest
28+
29+
.. image:: https://img.shields.io/conda/vn/conda-forge/pyctest.svg
30+
:target: https://anaconda.org/conda-forge/pyctest
31+
32+
.. image:: https://img.shields.io/conda/pn/conda-forge/pyctest.svg
33+
:target: https://anaconda.org/conda-forge/pyctest
34+
35+
.. image:: https://img.shields.io/conda/dn/conda-forge/pyctest.svg
36+
:target: https://anaconda.org/conda-forge/pyctest
37+
38+
###################
39+
Anaconda (jrmadsen)
40+
###################
41+
42+
.. image:: https://img.shields.io/badge/recipe-pyctest-green.svg
2743
:target: https://anaconda.org/jrmadsen/pyctest
2844

29-
.. image:: https://anaconda.org/jrmadsen/pyctest/badges/latest_release_date.svg
45+
.. image:: https://anaconda.org/jrmadsen/pyctest/badges/version.svg
3046
:target: https://anaconda.org/jrmadsen/pyctest
3147

3248
.. image:: https://anaconda.org/jrmadsen/pyctest/badges/platforms.svg

‎docs/install.rst

+39-22
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,17 @@ This section covers the basics of how to download and install PyCTest.
1010
Supported Environments
1111
======================
1212

13-
PyCTest is tested, built, and distributed for python 2.7 3.5 3.6 on Linux/macOS
14-
and python 3.5 3.6 on Windows 10.
13+
PyCTest is tested, built, and distributed for python 2.7, 3.6, and 3.7 on Linux/macOS through conda-forge.
14+
Windows support is possible but Anaconda compiler issues within conda-forge with respect to ``std::unique_ptr``
15+
are currently causing issues.
1516

1617
Installing from Conda (Recommended)
1718
===================================
1819

19-
If you only want to run PyCTest, not develop it, then you should install through
20-
a package manager. Conda, our supported package manager, can install PyCTest and
21-
its dependencies for you.
22-
2320
First, you must have `Conda <http://continuum.io/downloads>`_ installed,
2421
then open a terminal or a command prompt window and run::
2522

26-
$ conda install -c conda-forge PyCTest
23+
$ conda install -c conda-forge pyctest
2724

2825
This will install PyCTest and all the dependencies from the conda-forge channel.
2926

@@ -33,13 +30,13 @@ Updating the installation
3330
PyCTest is an active project, so we suggest you update your installation
3431
frequently. To update the installation run::
3532

36-
$ conda update -c conda-forge PyCTest
33+
$ conda update -c conda-forge pyctest
3734

3835
For some more information about using Conda, please refer to the
3936
`docs <http://conda.pydata.org/docs>`__.
4037

41-
Installing from source with Conda
42-
=================================
38+
Installing from source
39+
======================
4340

4441
Sometimes an adventurous user may want to get the source code, which is
4542
always more up-to-date than the one provided by Conda (with more bugs of
@@ -53,31 +50,51 @@ terminal and running::
5350
$ git clone https://github.com/jrmadsen/pyctest.git
5451

5552
in the folder where you want the source code. This will create a folder called
56-
`PyCTest` which contains a copy of the source code.
53+
`pyctest` which contains a copy of the source code.
5754

55+
Source installation is also available through `PyPi <https://pypi.org/project/pyctest/>`_::
56+
57+
$ pip install -vvv pyctest
5858

5959
Installing dependencies
6060
-----------------------
6161

62-
You will need to install all the dependencies listed in
63-
``requirements.txt`` or ``meta.yaml`` files. For example, requirements can be
64-
installed using Conda by running::
62+
You will need a C compiler, C++ compiler, CMake, Git, OpenSSL, and Curl
63+
on your system. Generally, these packages already exist on your system. The C++
64+
compiler requires support for C++11, in particular it needs to support lambdas and
65+
``std::unique_ptr``.
6566

66-
$ conda install --file requirements.txt
67+
After navigating to inside the `pyctest` directory, you can install PyCTest by
68+
building/compiling the shared libraries and either of the following standard Python
69+
installation commands:
6770

68-
After navigating to inside the `PyCTest` directory, you can install PyCTest by
69-
building/compiling the shared libraries and running the install script::
71+
.. code:: shell
7072
71-
$ python build.py
72-
$ pip install .
73+
$ pip install -vvv .
74+
$ python setup.py install
7375
7476
Common issues
7577
-------------
7678

77-
No issues with the current build system have been reported.
79+
- Lack of full C++11 support, particularly `std::unique_ptr`
7880

7981
Importing PyCTest
8082
=================
8183

82-
When importing, it is best to import PyCTest before importing numpy.
83-
See `this thread <https://github.com/jrmadsen/pyctest/issues/178>`_ for details.
84+
In general, the base module is not utilized directly. The following import scheme is generally simplest:
85+
86+
.. code:: python
87+
88+
import pyctest as _pyctest
89+
import pyctest.pyctest as pyctest
90+
import pyctest.pycmake as pycmake
91+
import pyctest.helpers as helpers
92+
from pyctest.cmake import CMake
93+
from pyctest.ctest import CTest
94+
from pyctest.cpack import CPack
95+
96+
print(_pyctest.version)
97+
CMake('--version')
98+
CTest('--version')
99+
CPack('--version')
100+

0 commit comments

Comments
 (0)