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)
 - hidapi >= 0.8.0 (optional, used for some HID based "serial cables")
 - bluez >= 4.0 (optional, used for Bluetooth communication)
 - libftdi1 >= 1.0 (optional, used by some drivers)
 - libgpib (optional, used by some drivers)
 - libieee1284 (optional, used by some drivers)
 - libgio >= 2.32.0 (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.4.0 (the libsigrok C library, see above)
 - A C++ compiler with C++11 support (-std=c++11 option), e.g.
   - g++ (>= 4.8.1)
   - clang++ (>= 3.3)
 - 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.4.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 Ruby bindings:

 - libsigrokcxx >= 0.4.0 (the libsigrok C++ bindings, see above)
 - Ruby >= 1.9.3 (including development files!)
 - SWIG >= 3.0.8
 - YARD (optional, only needed for the Ruby API docs)

Requirements for the Java bindings:

 - libsigrokcxx >= 0.4.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`
zip: Provide fallback if zip_discard() is unavailable zip_discard() was introduced in libzip 0.11, which some systems do not have yet. Provide a fallback replacement for zip_discard(), and reduce the requirement to libzip 0.10 again. This fixes bug #674. 2015-10-30 14:07:25 +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)`
serial: prepare serial over HID in common layer and build support Search for the optional HIDAPI library. Call the library's init and exit routine, and print version information. Extend the common serial layer's code paths for open, list, and find USB to also support serial over HID. This commit prepares serial over HID, but the HIDAPI specific transport for serial communication still is empty in this implementation. 2017-03-26 14:48:36 +00:00			`- hidapi >= 0.8.0 (optional, used for some HID based "serial cables")`
doc: update README for serial over Bluetooth Mention the optional external BlueZ dependency. Provide conn= examples for Bluetooth communication. Mention the UT-D07 adapter. 2018-12-30 18:18:10 +00:00			`- bluez >= 4.0 (optional, used for Bluetooth communication)`
Drop libftdi 0.x support, require libftdi 1.x. There were some issues when using libftdi 0.x recently that are fixed when switching to libftdi 1.x (not really worth the effort to investigate). libftdi 1.x has been around several years now and should be available in most recent distros and OSes. For the rare cases where it is not, it's easy enough to get it via backport packages, or build from source, or sigrok users can just use our binary installers for most OSes. This also "fixes"/obsoletes bug #959. 2017-09-17 14:55:50 +00:00			`- 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)`
README: Mention the missing libieee1284 requirement. 2016-01-29 17:30:32 +00:00			`- libieee1284 (optional, used by some drivers)`
README: Mention new (optional) libgio dependency. libgio may or may not be part of a larger libglib package, depending on OS and distro. 2019-10-26 19:30:42 +00:00			`- libgio >= 2.32.0 (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:`

README: Bump bindings requirements to the upcoming 0.4.0 release. 2016-01-29 17:31:00 +00:00			`- libsigrok >= 0.4.0 (the libsigrok C library, see above)`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- A C++ compiler with C++11 support (-std=c++11 option), e.g.`
README: Fix incorrect gcc/clang minimum versions. https://gcc.gnu.org/projects/cxx-status.html#cxx11 https://clang.llvm.org/cxx_status.html 2017-03-31 17:47:18 +00:00			`- g++ (>= 4.8.1)`
			`- clang++ (>= 3.3)`
README: Improve and update the requirements list. 2014-12-03 08:09:31 +00:00			`- 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:`

README: Bump bindings requirements to the upcoming 0.4.0 release. 2016-01-29 17:31:00 +00:00			`- libsigrokcxx >= 0.4.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)`

Implement Ruby bindings on top of SWIG/C++ bindings. 2016-01-11 13:31:47 +00:00			`Requirements for the Ruby bindings:`

README: Bump bindings requirements to the upcoming 0.4.0 release. 2016-01-29 17:31:00 +00:00			`- libsigrokcxx >= 0.4.0 (the libsigrok C++ bindings, see above)`
Implement Ruby bindings on top of SWIG/C++ bindings. 2016-01-11 13:31:47 +00:00			`- Ruby >= 1.9.3 (including development files!)`
			`- SWIG >= 3.0.8`
			`- YARD (optional, only needed for the Ruby API docs)`

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

README: Bump bindings requirements to the upcoming 0.4.0 release. 2016-01-29 17:31:00 +00:00			`- libsigrokcxx >= 0.4.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