Skip to content

Commit fdae95d

Browse files
z3ntuYouw
z3ntu
authored and
Youw
committed
README: convert to markdown
1 parent 121567d commit fdae95d

File tree

1 file changed

+135
-124
lines changed

1 file changed

+135
-124
lines changed

‎README.txt‎ renamed to ‎README.md‎

Lines changed: 135 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
1-
HIDAPI library for Windows, Linux, FreeBSD and Mac OS X
2-
=========================================================
1+
# HIDAPI library for Windows, Linux, FreeBSD and Mac OS X
32

4-
About
5-
======
3+
## About
64

75
HIDAPI is a multi-platform library which allows an application to interface
86
with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and Mac
@@ -11,11 +9,11 @@ can be embedded directly into a target application by adding a single source
119
file (per platform) and a single header.
1210

1311
HIDAPI has five back-ends:
14-
* Windows (using hid.dll)
15-
* Linux/hidraw (using the Kernel's hidraw driver)
16-
* Linux/libusb (using libusb-1.0)
17-
* FreeBSD (using libusb-1.0)
18-
* Mac (using IOHidManager)
12+
* Windows (using hid.dll)
13+
* Linux/hidraw (using the Kernel's hidraw driver)
14+
* Linux/libusb (using libusb-1.0)
15+
* FreeBSD (using libusb-1.0)
16+
* Mac (using IOHidManager)
1917

2018
On Linux, either the hidraw or the libusb back-end can be used. There are
2119
tradeoffs, and the functionality supported is slightly different.
@@ -38,14 +36,14 @@ Fox Toolkit (http://www.fox-toolkit.org). It will build on every platform
3836
which HIDAPI supports. Since it relies on a 3rd party library, building it
3937
is optional but recommended because it is so useful when debugging hardware.
4038

41-
What Does the API Look Like?
42-
=============================
39+
## What Does the API Look Like?
4340
The API provides the the most commonly used HID functions including sending
4441
and receiving of input, output, and feature reports. The sample program,
4542
which communicates with a heavily hacked up version of the Microchip USB
4643
Generic HID sample looks like this (with error checking removed for
4744
simplicity):
4845

46+
```c
4947
#ifdef WIN32
5048
#include <windows.h>
5149
#endif
@@ -108,24 +106,24 @@ int main(int argc, char* argv[])
108106

109107
return 0;
110108
}
109+
```
111110
112111
If you have your own simple test programs which communicate with standard
113112
hardware development boards (such as those from Microchip, TI, Atmel,
114113
FreeScale and others), please consider sending me something like the above
115114
for inclusion into the HIDAPI source. This will help others who have the
116115
same hardware as you do.
117116
118-
License
119-
========
117+
## License
120118
HIDAPI may be used by one of three licenses as outlined in LICENSE.txt.
121119
122-
Download
123-
=========
120+
## Download
124121
HIDAPI can be downloaded from github
125-
git clone git://github.com/signal11/hidapi.git
122+
```sh
123+
git clone git://github.com/signal11/hidapi.git
124+
```
126125

127-
Build Instructions
128-
===================
126+
## Build Instructions
129127

130128
This section is long. Don't be put off by this. It's not long because it's
131129
complicated to build HIDAPI; it's quite the opposite. This section is long
@@ -142,88 +140,97 @@ Visual Studio projects are provided. Even if you're going to embed HIDAPI
142140
into your project, it is still beneficial to build the example programs.
143141

144142

145-
Prerequisites:
146-
---------------
147-
148-
Linux:
149-
-------
150-
On Linux, you will need to install development packages for libudev,
151-
libusb and optionally Fox-toolkit (for the test GUI). On
152-
Debian/Ubuntu systems these can be installed by running:
153-
sudo apt-get install libudev-dev libusb-1.0-0-dev libfox-1.6-dev
154-
155-
If you downloaded the source directly from the git repository (using
156-
git clone), you'll need Autotools:
157-
sudo apt-get install autotools-dev autoconf automake libtool
158-
159-
FreeBSD:
160-
---------
161-
On FreeBSD you will need to install GNU make, libiconv, and
162-
optionally Fox-Toolkit (for the test GUI). This is done by running
163-
the following:
164-
pkg_add -r gmake libiconv fox16
165-
166-
If you downloaded the source directly from the git repository (using
167-
git clone), you'll need Autotools:
168-
pkg_add -r autotools
169-
170-
Mac:
171-
-----
172-
On Mac, you will need to install Fox-Toolkit if you wish to build
173-
the Test GUI. There are two ways to do this, and each has a slight
174-
complication. Which method you use depends on your use case.
175-
176-
If you wish to build the Test GUI just for your own testing on your
177-
own computer, then the easiest method is to install Fox-Toolkit
178-
using ports:
179-
sudo port install fox
180-
181-
If you wish to build the TestGUI app bundle to redistribute to
182-
others, you will need to install Fox-toolkit from source. This is
183-
because the version of fox that gets installed using ports uses the
184-
ports X11 libraries which are not compatible with the Apple X11
185-
libraries. If you install Fox with ports and then try to distribute
186-
your built app bundle, it will simply fail to run on other systems.
187-
To install Fox-Toolkit manually, download the source package from
188-
http://www.fox-toolkit.org, extract it, and run the following from
189-
within the extracted source:
190-
./configure && make && make install
191-
192-
Windows:
193-
---------
194-
On Windows, if you want to build the test GUI, you will need to get
195-
the hidapi-externals.zip package from the download site. This
196-
contains pre-built binaries for Fox-toolkit. Extract
197-
hidapi-externals.zip just outside of hidapi, so that
198-
hidapi-externals and hidapi are on the same level, as shown:
199-
200-
Parent_Folder
201-
|
202-
+hidapi
203-
+hidapi-externals
204-
205-
Again, this step is not required if you do not wish to build the
206-
test GUI.
207-
208-
209-
Building HIDAPI into a shared library on Unix Platforms:
210-
---------------------------------------------------------
143+
### Prerequisites:
144+
145+
#### Linux:
146+
On Linux, you will need to install development packages for libudev,
147+
libusb and optionally Fox-toolkit (for the test GUI). On
148+
Debian/Ubuntu systems these can be installed by running:
149+
```sh
150+
sudo apt-get install libudev-dev libusb-1.0-0-dev libfox-1.6-dev
151+
```
152+
153+
If you downloaded the source directly from the git repository (using
154+
git clone), you'll need Autotools:
155+
```sh
156+
sudo apt-get install autotools-dev autoconf automake libtool
157+
```
158+
159+
#### FreeBSD:
160+
On FreeBSD you will need to install GNU make, libiconv, and
161+
optionally Fox-Toolkit (for the test GUI). This is done by running
162+
the following:
163+
```sh
164+
pkg_add -r gmake libiconv fox16
165+
```
166+
167+
If you downloaded the source directly from the git repository (using
168+
git clone), you'll need Autotools:
169+
```sh
170+
pkg_add -r autotools
171+
```
172+
173+
#### Mac:
174+
On Mac, you will need to install Fox-Toolkit if you wish to build
175+
the Test GUI. There are two ways to do this, and each has a slight
176+
complication. Which method you use depends on your use case.
177+
178+
If you wish to build the Test GUI just for your own testing on your
179+
own computer, then the easiest method is to install Fox-Toolkit
180+
using ports:
181+
```sh
182+
sudo port install fox
183+
```
184+
185+
If you wish to build the TestGUI app bundle to redistribute to
186+
others, you will need to install Fox-toolkit from source. This is
187+
because the version of fox that gets installed using ports uses the
188+
ports X11 libraries which are not compatible with the Apple X11
189+
libraries. If you install Fox with ports and then try to distribute
190+
your built app bundle, it will simply fail to run on other systems.
191+
To install Fox-Toolkit manually, download the source package from
192+
http://www.fox-toolkit.org, extract it, and run the following from
193+
within the extracted source:
194+
```sh
195+
./configure && make && make install
196+
```
197+
198+
#### Windows:
199+
On Windows, if you want to build the test GUI, you will need to get
200+
the hidapi-externals.zip package from the download site. This
201+
contains pre-built binaries for Fox-toolkit. Extract
202+
hidapi-externals.zip just outside of hidapi, so that
203+
hidapi-externals and hidapi are on the same level, as shown:
204+
```
205+
Parent_Folder
206+
|
207+
+hidapi
208+
+hidapi-externals
209+
```
210+
Again, this step is not required if you do not wish to build the
211+
test GUI.
212+
213+
214+
### Building HIDAPI into a shared library on Unix Platforms:
211215

212216
On Unix-like systems such as Linux, FreeBSD, Mac, and even Windows, using
213217
Mingw or Cygwin, the easiest way to build a standard system-installed shared
214218
library is to use the GNU Autotools build system. If you checked out the
215219
source from the git repository, run the following:
216220

217-
./bootstrap
218-
./configure
219-
make
220-
make install <----- as root, or using sudo
221+
```sh
222+
./bootstrap
223+
./configure
224+
make
225+
make install # as root, or using sudo
226+
```
221227

222228
If you downloaded a source package (ie: if you did not run git clone), you
223-
can skip the ./bootstrap step.
229+
can skip the `./bootstrap` step.
224230

225231
./configure can take several arguments which control the build. The two most
226232
likely to be used are:
233+
```sh
227234
--enable-testgui
228235
Enable build of the Test GUI. This requires Fox toolkit to
229236
be installed. Instructions for installing Fox-Toolkit on
@@ -234,26 +241,28 @@ likely to be used are:
234241
be installed. The example above will put the headers in
235242
/usr/include and the binaries in /usr/lib. The default is to
236243
install into /usr/local which is fine on most systems.
237-
238-
Building the manual way on Unix platforms:
239-
-------------------------------------------
244+
```
245+
### Building the manual way on Unix platforms:
240246

241247
Manual Makefiles are provided mostly to give the user and idea what it takes
242248
to build a program which embeds HIDAPI directly inside of it. These should
243249
really be used as examples only. If you want to build a system-wide shared
244250
library, use the Autotools method described above.
245251

246-
To build HIDAPI using the manual makefiles, change to the directory
247-
of your platform and run make. For example, on Linux run:
248-
cd linux/
249-
make -f Makefile-manual
252+
To build HIDAPI using the manual makefiles, change to the directory
253+
of your platform and run make. For example, on Linux run:
254+
```sh
255+
cd linux/
256+
make -f Makefile-manual
257+
```
250258

251-
To build the Test GUI using the manual makefiles:
252-
cd testgui/
253-
make -f Makefile-manual
259+
To build the Test GUI using the manual makefiles:
260+
```sh
261+
cd testgui/
262+
make -f Makefile-manual
263+
```
254264

255-
Building on Windows:
256-
---------------------
265+
### Building on Windows:
257266

258267
To build the HIDAPI DLL on Windows using Visual Studio, build the .sln file
259268
in the windows/ directory.
@@ -287,8 +296,7 @@ not. To build using the DDK:
287296
by the build system which is appropriate for your environment. On
288297
Windows XP, this directory is objfre_wxp_x86/i386.
289298

290-
Cross Compiling
291-
================
299+
## Cross Compiling
292300

293301
This section talks about cross compiling HIDAPI for Linux using autotools.
294302
This is useful for using HIDAPI on embedded Linux targets. These
@@ -299,38 +307,41 @@ OpenEmbedded or Buildroot.
299307

300308
For the purpose of this section, it will be assumed that the following
301309
environment variables are exported.
310+
```sh
311+
$ export STAGING=$HOME/out
312+
$ export HOST=arm-linux
313+
```
302314

303-
$ export STAGING=$HOME/out
304-
$ export HOST=arm-linux
305-
306-
STAGING and HOST can be modified to suit your setup.
315+
`STAGING` and `HOST` can be modified to suit your setup.
307316

308-
Prerequisites
309-
--------------
317+
### Prerequisites
310318

311319
Note that the build of libudev is the very basic configuration.
312320

313321
Build Libusb. From the libusb source directory, run:
314-
./configure --host=$HOST --prefix=$STAGING
315-
make
316-
make install
322+
```sh
323+
./configure --host=$HOST --prefix=$STAGING
324+
make
325+
make install
326+
```
317327

318328
Build libudev. From the libudev source directory, run:
319-
./configure --disable-gudev --disable-introspection --disable-hwdb \
320-
--host=$HOST --prefix=$STAGING
321-
make
322-
make install
329+
```sh
330+
./configure --disable-gudev --disable-introspection --disable-hwdb \
331+
--host=$HOST --prefix=$STAGING
332+
make
333+
make install
334+
```
323335

324-
Building HIDAPI
325-
----------------
336+
### Building HIDAPI
326337

327338
Build HIDAPI:
328-
329-
PKG_CONFIG_DIR= \
330-
PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \
331-
PKG_CONFIG_SYSROOT_DIR=$STAGING \
332-
./configure --host=$HOST --prefix=$STAGING
333-
339+
```
340+
PKG_CONFIG_DIR= \
341+
PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \
342+
PKG_CONFIG_SYSROOT_DIR=$STAGING \
343+
./configure --host=$HOST --prefix=$STAGING
344+
```
334345

335346
Signal 11 Software - 2010-04-11
336347
2010-07-28

0 commit comments

Comments
 (0)