diff --git a/HACKING.md b/HACKING.md index 56930af..da1b244 100644 --- a/HACKING.md +++ b/HACKING.md @@ -15,41 +15,54 @@ Here are some directions to get you started: Helper script to get some uniformity in the style: $ make style - If you use vim see the "Vim: How to prevent trailing whitespaces" - http://www.carbon-project.org/Vim__How_to_prevent_trailing_whitespaces.html + If you use vim see the [Vim: How to prevent trailing whitespaces](http://www.carbon-project.org/Vim__How_to_prevent_trailing_whitespaces.html). 2. Chase warnings: no warning should be introduced by your changes Depending what you touch, you can check with: + 2.1 When using autotools - $ autoreconf -Wall -vis + + $ autoreconf -Wall -vis + 2.2 When compiling + 2.2.1 Using extra flags: - $ export CFLAGS="-Wall -g -O2 -Wextra -pipe -funsigned-char -fstrict-aliasing \ - -Wchar-subscripts -Wundef -Wshadow -Wcast-align -Wwrite-strings -Wunused \ - -Wuninitialized -Wpointer-arith -Wredundant-decls -Winline -Wformat \ - -Wformat-security -Wswitch-enum -Winit-self -Wmissing-include-dirs \ - -Wmissing-prototypes -Wstrict-prototypes -Wold-style-definition \ - -Wbad-function-cast -Wnested-externs -Wmissing-declarations" - $ ./configure - $ make clean - $ make + + $ export CFLAGS="-Wall -g -O2 -Wextra -pipe -funsigned-char -fstrict-aliasing \ + -Wchar-subscripts -Wundef -Wshadow -Wcast-align -Wwrite-strings -Wunused \ + -Wuninitialized -Wpointer-arith -Wredundant-decls -Winline -Wformat \ + -Wformat-security -Wswitch-enum -Winit-self -Wmissing-include-dirs \ + -Wmissing-prototypes -Wstrict-prototypes -Wold-style-definition \ + -Wbad-function-cast -Wnested-externs -Wmissing-declarations" + $ ./configure + $ make clean + $ make + 2.2.2 Using clang: - You can use same CFLAGS but also "-Wunreachable-code" - $ scan-build ./configure - $ make clean - $ scan-build make - 2.2.3 Using cppcheck (v1.58 or higher): - $ make cppcheck + + You can use same CFLAGS but also `-Wunreachable-code` + + $ scan-build ./configure + $ make clean + $ scan-build make + + 2.2.3 Using `cppcheck` (v1.58 or higher): + + $ make cppcheck + 2.3 When Debianizing - $ lintian --info --display-info --display-experimental *deb - or (shorter version) - $ lintian -iIE *deb + + $ lintian --info --display-info --display-experimental *deb + or (shorter version) + $ lintian -iIE *deb 3. Preserve cross-platform compatility + The source code should remain compilable across various platforms, including some you probably cannot test alone so keep it in mind. Supported platforms: + - Linux - FreeBSD - Mac OS X - - Windows with Mingw + - Windows with MinGW diff --git a/README-Windows.md b/README-Windows.md index bf4ba69..8b22bf2 100644 --- a/README-Windows.md +++ b/README-Windows.md @@ -1,16 +1,16 @@ -*- -* Free/Libre Near Field Communication (NFC) library -* -* Libnfc historical contributors: -* Copyright (C) 2009 Roel Verdult -* Copyright (C) 2009-2013 Romuald Conty -* Copyright (C) 2010-2012 Romain Tartière -* Copyright (C) 2010-2013 Philippe Teuwen -* Copyright (C) 2012-2013 Ludovic Rousseau -* Additional contributors of Windows-specific parts: -* Copyright (C) 2010 Glenn Ergeerts -* Copyright (C) 2013 Alex Lian --* + *- + * Free/Libre Near Field Communication (NFC) library + * + * Libnfc historical contributors: + * Copyright (C) 2009 Roel Verdult + * Copyright (C) 2009-2013 Romuald Conty + * Copyright (C) 2010-2012 Romain Tartière + * Copyright (C) 2010-2013 Philippe Teuwen + * Copyright (C) 2012-2013 Ludovic Rousseau + * Additional contributors of Windows-specific parts: + * Copyright (C) 2010 Glenn Ergeerts + * Copyright (C) 2013 Alex Lian + -* Requirements ============ @@ -20,7 +20,7 @@ Requirements - CMake 2.8 [3] This was tested on Windows 7 64 bit, but should work on Windows Vista and -Windows XP and 32 bit as well. +Windows XP and 32 bit as well. Only the ACS ACR122 and the ASK Logo readers are tested at the moment, so any feedback about other devices is very welcome. Community forum: http://www.libnfc.org/community/ @@ -33,34 +33,38 @@ is an example of how to generate a distribution with the above mentioned requirements fulfilled (it is assumed the CMake binaries are in the system path, this is optional during installation of CMake): -- Add the following directories to your PATH : c:\MinGW64\bin;c:\MinGW64\x86_64-w64-mingw32\lib32;c:\MinGW64\x86_64-w64-mingw32\include +- Add the following directories to your PATH: + + c:\MinGW64\bin;c:\MinGW64\x86_64-w64-mingw32\lib32;c:\MinGW64\x86_64-w64-mingw32\include - Now it is possible to run CMake and mingw32-make: - C:\dev\libnfc-read-only> mkdir ..\libnfc-build - C:\dev\libnfc-read-only> cd ..\libnfc-build - C:\dev\libnfc-build> cmake-gui . - + C:\dev\libnfc-read-only> mkdir ..\libnfc-build + C:\dev\libnfc-read-only> cd ..\libnfc-build + C:\dev\libnfc-build> cmake-gui . + Now you can configure the build. Press "Configure", specify "MinGW32 Makefiles" and then you have the opportunity to set some configuration variables. If you don't want a Debug build change the variable CMAKE_BUILD_TYPE to "Release". If a non-GUI solution is preferred one can use: - C:\dev\libnfc-build> cmake -G "MinGW Makefiles" + C:\dev\libnfc-build> cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release ..\libnfc-read-only Now run mingw32-make to build: - C:\dev\libnfc-read-only\bin> mingw32-make - + C:\dev\libnfc-read-only\bin> mingw32-make + The build will create a shared library for Windows (nfc.dll) to link your applications against. It will compile -the tools against this shared library. +the tools against this shared library. References ========== -[1] the easiest way is to use the TDM-GCC installer. +[1] the easiest way is to use the TDM-GCC installer. Make sure to select MinGW-w64 in the installer, the regular MinGW does not contain headers for PCSC. http://sourceforge.net/projects/tdm-gcc/files/TDM-GCC%20Installer/tdm64-gcc-4.5.1.exe/download + [2] http://sourceforge.net/projects/libusb-win32/files/ + [3] http://www.cmake.org diff --git a/README.md b/README.md index 74f03a0..b03551f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ +``` *- * Free/Libre Near Field Communication (NFC) library -* +* * Libnfc historical contributors: * Copyright (C) 2009 Roel Verdult * Copyright (C) 2009-2015 Romuald Conty @@ -10,6 +11,7 @@ * Additional contributors: * See AUTHORS file -* +``` General Information =================== @@ -46,11 +48,12 @@ http://cutter.sf.net Installation ============ -See the file 'INSTALL' for configure, build and install details. +See the file `INSTALL` for configure, build and install details. Additionnally, you may need to grant permissions to your user to drive your device. Under GNU/Linux systems, if you use udev, you could use the provided udev rules. e.g. under Debian, Ubuntu, etc. + sudo cp contrib/udev/42-pn53x.rules /lib/udev/rules.d/ Under FreeBSD, if you use devd, there is also a rules file: contrib/devd/pn53x.conf. @@ -64,16 +67,20 @@ configuration file located in sysconfdir (as provided to ./configure). A sample commented file is available in sources: libnfc.conf.sample If you have compiled using: - ./configure --prefix=/usr --sysconfdir=/etc + + ./configure --prefix=/usr --sysconfdir=/etc + you can make configuration directory and copy the sample file: - sudo mkdir /etc/nfc - sudo cp libnfc.conf.sample /etc/nfc/libnfc.conf + + sudo mkdir /etc/nfc + sudo cp libnfc.conf.sample /etc/nfc/libnfc.conf To configure multiple devices, you can either modify libnfc.conf or create a file per device in a nfc/devices.d directory: - sudo mkdir -p /etc/nfc/devices.d - printf 'name = "My first device"\nconnstring = "pn532_uart:/dev/ttyACM0"\n' | sudo tee /etc/nfc/devices.d/first.conf - printf 'name = "My second device"\nconnstring = "pn532_uart:/dev/ttyACM1"\n' | sudo tee /etc/nfc/devices.d/second.conf + + sudo mkdir -p /etc/nfc/devices.d + printf 'name = "My first device"\nconnstring = "pn532_uart:/dev/ttyACM0"\n' | sudo tee /etc/nfc/devices.d/first.conf + printf 'name = "My second device"\nconnstring = "pn532_uart:/dev/ttyACM1"\n' | sudo tee /etc/nfc/devices.d/second.conf How to report bugs ================== @@ -82,7 +89,7 @@ To report a bug, visit https://github.com/nfc-tools/libnfc/issues and fill out a bug report form. If you have questions, remarks, we encourage you to post this in the developers -community: +community: http://www.libnfc.org/community Please make sure to include: @@ -99,14 +106,17 @@ Please make sure to include: * A trace with debug activated. Reproduce the bug with debug, e.g. if it was: - $ nfc-list -v + + $ nfc-list -v + run it as: - $ LIBNFC_LOG_LEVEL=3 nfc-list -v + + $ LIBNFC_LOG_LEVEL=3 nfc-list -v * How to reproduce the bug. - Please include a short test program that exhibits the behavior. - As a last resort, you can also provide a pointer to a larger piece + Please include a short test program that exhibits the behavior. + As a last resort, you can also provide a pointer to a larger piece of software that can be downloaded. * If the bug was a crash, the exact text that was printed out @@ -128,8 +138,8 @@ Building It should be as simple as running these two commands: -./configure -make + ./configure + make Troubleshooting =============== @@ -137,27 +147,27 @@ Troubleshooting Touchatag/ACR122: ----------------- If your Touchatag or ACR122 device fails being detected by libnfc, make sure -that PCSC-lite daemon (pcscd) is installed and is running. +that PCSC-lite daemon (`pcscd`) is installed and is running. If your Touchatag or ACR122 device fails being detected by PCSC-lite daemon -(pcsc_scan doesn't see anything) then try removing the bogus firmware detection +(`pcsc_scan` doesn't see anything) then try removing the bogus firmware detection of libccid: edit libccid_Info.plist configuration file (usually -/etc/libccid_Info.plist) and locate "ifdDriverOptions", turn -"0x0000" value into 0x0004 to allow bogus devices and restart +`/etc/libccid_Info.plist`) and locate `ifdDriverOptions`, turn +`0x0000` value into `0x0004` to allow bogus devices and restart pcscd daemon. ACR122: ------- Using an ACR122 device with libnfc and without tag (e.g. to use NFCIP modes or card emulation) needs yet another PCSC-lite tweak: You need to allow usage of -CCID Exchange command. To do this, edit libccid_Info.plist configuration file -(usually /etc/libccid_Info.plist) and locate "ifdDriverOptions", -turn "0x0000" value into 0x0001 to allow CCID exchange or -0x0005 to allow CCID exchange and bogus devices (cf previous remark) and +CCID Exchange command. To do this, edit `libccid_Info.plist` configuration file +(usually `/etc/libccid_Info.plist`) and locate `ifdDriverOptions`, +turn `0x0000` value into `0x0001` to allow CCID exchange or +`0x0005` to allow CCID exchange and bogus devices (cf previous remark) and restart pcscd daemon. Warning: if you use ACS CCID drivers (acsccid), configuration file is located -in something like: /usr/lib/pcsc/drivers/ifd-acsccid.bundle/Contents/Info.plist +in something like: `/usr/lib/pcsc/drivers/ifd-acsccid.bundle/Contents/Info.plist` SCL3711: -------- @@ -172,7 +182,8 @@ Since Linux kernel version 3.1, two kernel-modules must not be loaded in order to use libnfc : "nfc" and "pn533". To prevent kernel from loading automatically these modules, you can blacklist them in a modprobe conf file. This file is provided within libnfc archive: - sudo cp contrib/linux/blacklist-libnfc.conf /etc/modprobe.d/blacklist-libnfc.conf + + sudo cp contrib/linux/blacklist-libnfc.conf /etc/modprobe.d/blacklist-libnfc.conf Proprietary Notes ================= @@ -181,4 +192,3 @@ FeliCa is a registered trademark of the Sony Corporation. MIFARE is a trademark of NXP Semiconductors. Jewel Topaz is a trademark of Innovision Research & Technology. All other trademarks are the property of their respective owners. -