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
------------

 - git
 - gcc (>= 4.0)
 - make
 - autoconf >= 2.63
 - automake >= 1.11
 - libtool
 - pkg-config >= 0.22
 - libglib >= 2.32.0
 - libzip >= 0.10
 - libserialport >= 0.1.0 (optional, used by some drivers)
 - librevisa >= 0.0.20130812 (optional, used by some drivers)
 - libusb-1.0 >= 1.0.16 (optional, used by some drivers)
 - libftdi >= 0.16 (optional, used by some drivers)
 - check >= 0.9.4 (optional, only needed to run unit tests)


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


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 lists
-------------

There are two mailing lists for sigrok/libsigrok:

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


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`
			`------------`

			`- git`
sr: Mark API functions with SR_API/SR_PRIV. Use SR_API to mark public API symbols, and SR_PRIV for private symbols. Variables and functions marked 'static' are private already and don't need SR_PRIV. However, functions which are not static (because they need to be used in other libsigrok-internal files) but are also not meant to be part of the public libsigrok API, must use SR_PRIV. This uses the 'visibility' feature of gcc (requires gcc >= 4.0). Details: http://gcc.gnu.org/wiki/Visibility 2012-02-01 22:40:35 +00:00			`- gcc (>= 4.0)`
Update/enforce/document our build requirements. 2012-01-28 20:26:56 +00:00			`- make`
			`- autoconf >= 2.63`
			`- automake >= 1.11`
			`- libtool`
			`- pkg-config >= 0.22`
Bump glib requirement to >= 2.32.0. This is now required, e.g. due to the usage of g_variant_new_fixed_array(). 2013-04-12 16:47:06 +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`
Update to 3-digit libserialport package version format. 2013-11-22 14:13:04 +00:00			`- libserialport >= 0.1.0 (optional, used by some drivers)`
README: Mention missing dependency 'librevisa'. 2014-05-04 20:04:37 +00:00			`- librevisa >= 0.0.20130812 (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 alsa (optional) library. 2013-01-19 18:13:52 +00:00			`- libftdi >= 0.16 (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)`
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

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.`


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

			`There are two mailing lists for sigrok/libsigrok:`

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


			`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