libsigrok/README

-------------------------------------------------------------------------------
README
-------------------------------------------------------------------------------

The sigrok project aims at creating a portable, cross-platform,
Free/Libre/Open-Source signal analysis software suite that supports various
device types (such as logic analyzers, oscilloscopes, multimeters, and more).

libsigrok is a shared library written in C which provides the basic API
for talking to hardware and reading/writing the acquired data into various
input/output file formats.


Status
------

libsigrok is in a usable state and has had official tarball releases.

While the API can change from release to release, this will always be
properly documented and reflected in the package version number and
in the shared library / libtool / .so-file version numbers.

However, there are _NO_ guarantees at all for stable APIs in git snapshots!
Distro packagers should only use released tarballs (no git snapshots).


Requirements
------------

Requirements for the C library:

 - git (only needed when building from git)
 - gcc (>= 4.0) or clang
 - make
 - autoconf >= 2.63 (only needed when building from git)
 - automake >= 1.11 (only needed when building from git)
 - libtool (only needed when building from git)
 - pkg-config >= 0.22
 - libglib >= 2.32.0
 - libzip >= 0.10
 - libserialport >= 0.1.1 (optional, used by some drivers)
 - librevisa >= 0.0.20130412 (optional, used by some drivers)
 - libusb-1.0 >= 1.0.16 (optional, used by some drivers)
 - libftdi >= 0.16 or libftdi1 >= 1.0 (optional, used by some drivers)
 - libgpib (optional, used by some drivers)
 - check >= 0.9.4 (optional, only needed to run unit tests)
 - doxygen (optional, only needed for the C API docs)
 - graphviz (optional, only needed for the C API docs)

Requirements for the C++ bindings:

 - libsigrok >= 0.3.0 (the libsigrok C library, see above)
 - A C++ compiler with C++11 support (-std=c++11 option), e.g.
   - g++ (>= 4.7)
   - clang++ (>= 3.1)
 - autoconf-archive (only needed when building from git)
 - doxygen (required for building the bindings, not only for C++ API docs!)
 - graphviz (optional, only needed for the C++ API docs)
 - Python (2 or 3) executable (development files are not needed)
 - glibmm-2.4 (>= 2.32.0)

Requirements for the Python bindings:

 - libsigrokcxx >= 0.3.0 (the libsigrok C++ bindings, see above)
 - Python >= 2.7 or Python >= 3 (including development files!)
 - Python setuptools (for Python 2 or 3)
 - pygobject >= 3.0.0 (for Python 2 or 3), a.k.a python-gi
 - numpy (for Python 2 or 3)
 - SWIG >= 2.0.0
 - doxygen (optional, only needed for the Python API docs)
 - graphviz (optional, only needed for the Python API docs)
 - doxypy (optional, only needed for the Python API docs)

Requirements for the Java bindings:

 - libsigrokcxx >= 0.3.0 (the libsigrok C++ bindings, see above)
 - SWIG >= 2.0.0
 - Java JDK (for JNI includes and the javac/jar binaries)
 - doxygen (optional, only needed for the Java API docs)
 - graphviz (optional, only needed for the Java API docs)


Building and installing
-----------------------

In order to get the libsigrok source code and build it, run:

 $ git clone git://sigrok.org/libsigrok
 $ cd libsigrok
 $ ./autogen.sh
 $ ./configure
 $ make

For installing libsigrok:

 $ make install

See INSTALL or the following wiki page for more (OS-specific) instructions:

 http://sigrok.org/wiki/Building

Please also check the following wiki page in case you encounter any issues:

 http://sigrok.org/wiki/Building#FAQ


Device-specific issues
----------------------

Please check README.devices for some notes and hints about device- or
driver-specific issues to be aware of.


Firmware
--------

Some devices supported by libsigrok need a firmware to be uploaded before the
device can be used. See README.devices for details.


Copyright and license
---------------------

libsigrok is licensed under the terms of the GNU General Public License
(GPL), version 3 or later.

While some individual source code files are licensed under the GPLv2+, and
some files are licensed under the GPLv3+, this doesn't change the fact that
the library as a whole is licensed under the terms of the GPLv3+.

Please see the individual source files for the full list of copyright holders.


Mailing list
------------

 https://lists.sourceforge.net/lists/listinfo/sigrok-devel


IRC
---

You can find the sigrok developers in the #sigrok IRC channel on Freenode.


Website
-------

 http://sigrok.org/wiki/Libsigrok
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00			`-------------------------------------------------------------------------------`
			`README`
			`-------------------------------------------------------------------------------`

			`The sigrok project aims at creating a portable, cross-platform,`
updated URLs and description 2012-10-08 16:52:36 +00:00			`Free/Libre/Open-Source signal analysis software suite that supports various`
README: Add status, update URL, small fixes. 2012-10-10 21:08:32 +00:00			`device types (such as logic analyzers, oscilloscopes, multimeters, and more).`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00
			`libsigrok is a shared library written in C which provides the basic API`
updated URLs and description 2012-10-08 16:52:36 +00:00			`for talking to hardware and reading/writing the acquired data into various`
			`input/output file formats.`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00

README: Add status, update URL, small fixes. 2012-10-10 21:08:32 +00:00			`Status`
			`------`

			`libsigrok is in a usable state and has had official tarball releases.`

			`While the API can change from release to release, this will always be`
			`properly documented and reflected in the package version number and`
			`in the shared library / libtool / .so-file version numbers.`

			`However, there are _NO_ guarantees at all for stable APIs in git snapshots!`
			`Distro packagers should only use released tarballs (no git snapshots).`


Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00			`Requirements`
			`------------`

README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`Requirements for the C library:`

			`- git (only needed when building from git)`
			`- gcc (>= 4.0) or clang`
Update/enforce/document our build requirements. 2012-01-28 20:26:56 +00:00			`- make`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- autoconf >= 2.63 (only needed when building from git)`
			`- automake >= 1.11 (only needed when building from git)`
			`- libtool (only needed when building from git)`
Update/enforce/document our build requirements. 2012-01-28 20:26:56 +00:00			`- pkg-config >= 0.22`
Lower dependency to glib 2.32. By avoiding g_slist_copy_deep() for now, we can easily allow libsigrok to build against glib 2.32 (less hassle for users of stable/older distros or OSes). 2015-01-29 07:51:31 +00:00			`- libglib >= 2.32.0`
Bump libzip requirement to >= 0.10. We now use zip_int64_t and zip_get_num_entries() for example, which requires at least libzip 0.10. This version was released in 03/2012, which is old enough that we don't necessarily have to do a work-around for older versions. Thus, simply bump the requirement to >= 0.10. 2013-10-16 16:10:29 +00:00			`- libzip >= 0.10`
Lower libserialport requirement to 0.1.1. 2015-04-19 16:39:35 +00:00			`- libserialport >= 0.1.1 (optional, used by some drivers)`
Check for librevisa >= 0.0.20130412 - the latest official release 2015-01-23 22:55:14 +00:00			`- librevisa >= 0.0.20130412 (optional, used by some drivers)`
Bump minimum libusb version to 1.0.16 This gets us the libusb version checking mechanism itself, hopefully making this sort of thing easier in future. Also hotplug, device tree traversal, and lots of fixes. 2013-12-19 09:45:36 +00:00			`- libusb-1.0 >= 1.0.16 (optional, used by some drivers)`
README: Document that libftdi1 is also an option. 2014-06-16 11:20:56 +00:00			`- libftdi >= 0.16 or libftdi1 >= 1.0 (optional, used by some drivers)`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- libgpib (optional, used by some drivers)`
Add a testsuite for libsigrok. This adds a suite of unit tests for libsigrok. It uses the 'Check' tool/library (apt-get install check) to run the tests. The configure tool tries to find libcheck. If it succeeds, a "make check" will run all tests. Otherwise, none of the tests will be built and "make check" will not run any tests. This also means that users who don't have 'check' installed will still be able to build and install libsigrok just fine. 2013-03-07 08:37:42 +00:00			`- check >= 0.9.4 (optional, only needed to run unit tests)`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- doxygen (optional, only needed for the C API docs)`
			`- graphviz (optional, only needed for the C API docs)`

			`Requirements for the C++ bindings:`

			`- libsigrok >= 0.3.0 (the libsigrok C library, see above)`
			`- A C++ compiler with C++11 support (-std=c++11 option), e.g.`
			`- g++ (>= 4.7)`
			`- clang++ (>= 3.1)`
			`- autoconf-archive (only needed when building from git)`
			`- doxygen (required for building the bindings, not only for C++ API docs!)`
			`- graphviz (optional, only needed for the C++ API docs)`
			`- Python (2 or 3) executable (development files are not needed)`
			`- glibmm-2.4 (>= 2.32.0)`

			`Requirements for the Python bindings:`

Rename libsigrokxx to the more common libsigrokcxx. 2015-01-17 17:49:04 +00:00			`- libsigrokcxx >= 0.3.0 (the libsigrok C++ bindings, see above)`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- Python >= 2.7 or Python >= 3 (including development files!)`
			`- Python setuptools (for Python 2 or 3)`
			`- pygobject >= 3.0.0 (for Python 2 or 3), a.k.a python-gi`
			`- numpy (for Python 2 or 3)`
README: Require SWIG >= 2.0.0. We use %shared_ptr for example, which was introduced in SWIG 2.0.0. 2014-12-06 21:27:47 +00:00			`- SWIG >= 2.0.0`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- doxygen (optional, only needed for the Python API docs)`
			`- graphviz (optional, only needed for the Python API docs)`
			`- doxypy (optional, only needed for the Python API docs)`

			`Requirements for the Java bindings:`

Rename libsigrokxx to the more common libsigrokcxx. 2015-01-17 17:49:04 +00:00			`- libsigrokcxx >= 0.3.0 (the libsigrok C++ bindings, see above)`
README: Require SWIG >= 2.0.0. We use %shared_ptr for example, which was introduced in SWIG 2.0.0. 2014-12-06 21:27:47 +00:00			`- SWIG >= 2.0.0`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- Java JDK (for JNI includes and the javac/jar binaries)`
			`- doxygen (optional, only needed for the Java API docs)`
			`- graphviz (optional, only needed for the Java API docs)`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00

			`Building and installing`
			`-----------------------`

			`In order to get the libsigrok source code and build it, run:`

updated URLs and description 2012-10-08 16:52:36 +00:00			`$ git clone git://sigrok.org/libsigrok`
			`$ cd libsigrok`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00			`$ ./autogen.sh`
			`$ ./configure`
			`$ make`

			`For installing libsigrok:`

			`$ make install`

README: Refer to INSTALL and new Building wiki page. 2013-03-17 11:53:08 +00:00			`See INSTALL or the following wiki page for more (OS-specific) instructions:`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00
README: Refer to INSTALL and new Building wiki page. 2013-03-17 11:53:08 +00:00			`http://sigrok.org/wiki/Building`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00
Mention the Building#FAQ wiki page for common issues. 2015-01-03 16:38:06 +00:00			`Please also check the following wiki page in case you encounter any issues:`

			`http://sigrok.org/wiki/Building#FAQ`

Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00
Add initial README.devices file. 2013-03-13 09:33:17 +00:00			`Device-specific issues`
			`----------------------`
sr: README: Add section about firmware files. 2012-05-30 20:23:36 +00:00
Add initial README.devices file. 2013-03-13 09:33:17 +00:00			`Please check README.devices for some notes and hints about device- or`
			`driver-specific issues to be aware of.`
sr: README: Add section about firmware files. 2012-05-30 20:23:36 +00:00

Add initial README.devices file. 2013-03-13 09:33:17 +00:00			`Firmware`
			`--------`
sr: README: Add section about firmware files. 2012-05-30 20:23:36 +00:00
Add initial README.devices file. 2013-03-13 09:33:17 +00:00			`Some devices supported by libsigrok need a firmware to be uploaded before the`
			`device can be used. See README.devices for details.`
sr: README: Add section about firmware files. 2012-05-30 20:23:36 +00:00

README: Add "Copyright and license" section. 2013-04-26 11:35:19 +00:00			`Copyright and license`
			`---------------------`

			`libsigrok is licensed under the terms of the GNU General Public License`
			`(GPL), version 3 or later.`

			`While some individual source code files are licensed under the GPLv2+, and`
			`some files are licensed under the GPLv3+, this doesn't change the fact that`
			`the library as a whole is licensed under the terms of the GPLv3+.`

			`Please see the individual source files for the full list of copyright holders.`


Drop references to obsolete sigrok-commits mailing list. 2014-07-22 21:54:18 +00:00			`Mailing list`
			`------------`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00
			`https://lists.sourceforge.net/lists/listinfo/sigrok-devel`


			`IRC`
			`---`

			`You can find the sigrok developers in the #sigrok IRC channel on Freenode.`


			`Website`
			`-------`

README: Add status, update URL, small fixes. 2012-10-10 21:08:32 +00:00			`http://sigrok.org/wiki/Libsigrok`
Split README, add appropriate ones per-project. 2011-12-30 21:38:25 +00:00