Updated documentation regarding compatibility, use on macOS, and cont…

…ributions

README

@@ -79,6 +79,13 @@ documentation whether it can be achieved by using libfaketime directly.
   the linker to do so at application start time. libfaketime will not work with
   those applications unless you can modify them.
 
+  This apparently happens a lot in complex run-time environments, e.g., for
+  programs written in golang, for some Java Virtual Machine implementations,
+  etc. Since libfaketime is effectively bypassed in such situations, there's
+  nothing we can do about it. Please consider asking the appropriate developers
+  and vendors to implement their runtime environment in a way that supports
+  intercepting selected system calls through LD_PRELOAD.
+
 * Applications can explicitly be designed to prevent libfaketime from working,
   e.g., by checking whether certain environment variables are set or whether
   libfaketime-specific files are present.

README.OSX

@@ -4,17 +4,15 @@ README file for libfaketime on macOS
 Support for macOS has meanwhile matured and many command line and
 GUI applications will run stable.
 
-Developments and tests are done on High Sierra currently.
-Use libfaketime 0.9.6 or earlier on OS X (i.e., before Sierra).
+Developments and tests are done on Mojave currently.
 
-Version 0.9.5 and higher no longer works with OSX <= 10.6 due to
+Version 0.9.5 and higher no longer work with OSX <= 10.6 due to
 changes in the underlying system libraries. If you need libfaketime
 on OSX <= 10.6, please use libfaketime version 0.9.
 
-
-Installing and using libfaketime on OS X is slightly different than
+Installing and using libfaketime on macOS is slightly different than
 on Linux. Please make sure to read the README file for general
-setup and usage, and refer to this file only about OS X specifics.
+setup and usage, and refer to this file only about macOS specifics.
 
 
 1) Installing libfaketime on macOS
@@ -33,6 +31,10 @@ Or, if you use Homebrew, install using:
 
     brew install libfaketime
 
+Please inform the respective package maintainers if the latest release
+is not yet available this way. With homebrew, you can typically use
+"brew install --HEAD" to install from the latest source automatically.
+
 Otherwise, you have to compile and install libfaketime manually; this
 will require a working installation of Xcode and its command line tools
 on your machine.
@@ -55,7 +57,7 @@ output is correct:
 ---------------------------------------------------
 
 You will need to set three environment variables. In a Terminal.app
-or iTerm2 session, the following commands can be used:
+or any other CLI session, the following commands can be used:
 
 export DYLD_FORCE_FLAT_NAMESPACE=1
 export DYLD_INSERT_LIBRARIES=/path/to/libfaketime.1.dylib
@@ -76,7 +78,7 @@ for help and use "man faketime" for details.
 --------------------------------------------
 
 Given the limited number of system calls libfaketime intercepts,
-it may not work too well with specific GUI applications on OS X.
+it may not work too well with specific GUI applications on macOS.
 This can result in crashes after a seemingly random time, or an
 application will not or at least not always see the faked time,
 and so on.
@@ -127,18 +129,26 @@ time-related system calls that need to be intercepted on macOS.
 
     https://github.com/wolfcw/libfaketime/issues
 
-Important: When reporting non-working applications, please make
-sure that your issue is not related to SIP (system integrity
-protection). For example, on a SIP-enabled, default macOS installation,
-libfaketime will not work for programs like /bin/bash because
-the path /bin is SIP-protected. Copy your application to a
-non-SIP-protected path, and if libfaketime still does not work,
-feel free to report it.
+However, there are two important aspects:
+
+- When reporting non-working applications, please make sure that your issue is
+  not related to SIP (system integrity protection). For example, on a
+  SIP-enabled, default macOS installation, libfaketime will not work for
+  programs like /bin/bash because the path /bin is SIP-protected. Copy your
+  application to a non-SIP-protected path, and if libfaketime still does not
+  work, feel free to report it.
+
+- We cannot and will not help with using libfaketime for proprietary or
+  commercial software unless you are its developer trying to integrate
+  libfaketime. Please contact the developers or the vendor directly if
+  you have problems using libfaketime with non-free / not open sourced
+  macOS applications.
 
 
 4) Notes for developers of macOS applications
 ---------------------------------------------
 
 The environment variable FAKETIME can be changed at application run-time
 and always takes precedence over other user-controlled settings. It can
-be re-set to 0 (zero) to work around potential incompatibilities.
+be re-set to 0 (zero) to work around potential incompatibilities or if
+you do not want libfaketime applied to your software.

README.developers

@@ -4,20 +4,27 @@ This file contains information for libfaketime developers and contributors.
 GENERAL
 =======
 
-Starting with libfaketime v0.9.5, development and issue handling is 
-completely done via Github: 
+Starting with libfaketime v0.9.5, development and issue handling is
+completely done via Github:
 
 	https://github.com/wolfcw/libfaketime
 
-- Official releases are tagged. 
-- Code contributions and bugfixes are merged into the "development" branch, 
-  which is considered unstable and may contain code that is not yet fully 
-  tested.
+- Official releases are tagged.
+
+- Code contributions and bugfixes should be submitted to and then merged into
+  the "development" branch, which is considered unstable and may contain code
+  that is not yet fully tested.
+
 - The "master" branch is updated with tested code only; it is ensured that
-  it compiles and works cleanly at least on current Linux and OS X systems.
+  it compiles and works cleanly at least on current Linux and macOS systems.
 
 Code contributions are highly welcome, preferably via pull requests on Github.
 
+Please have a look at issues labelled as "help wanted" in the Github issue
+tracker. If you are interested in contributing to libfaketime, helping with
+these issues is not only much appreciated, but also a good way to familiarize
+yourself with the overall codebase.
+
 
 CODE STYLE
 ==========
@@ -43,16 +50,16 @@ void do_nothing(int how_often)
   }
 }
 
-- Use -DDEBUG and #ifdef DEBUG for development and testing. Avoid printing
-  to stdout or stderr outside "#ifdef DEBUG"; if it is necessary to inform
-  the user a run-time, prefix your output with "faketime" or make otherwise
-  sure that the user knows where the message is coming from.  
+- Use -DDEBUG and #ifdef DEBUG for development and testing. Avoid printing to
+  stdout or stderr outside "#ifdef DEBUG"; if it is necessary to inform the
+  user a run-time, prefix your output with "libfaketime" or make otherwise sure
+  that the user knows where the message is coming from.
 
 - If you add new functions to libfaketime.c, try placing them somewhere
   where they fit will: Usually, functions are grouped by functionality
   (e.g., all functions related to faking file timestamps). If that's not
   possible, group them by contributor, or document your placement strategy
-  in the commit message. 
+  in the commit message.
 
 
 DEVELOPMENT, BUILDING, AND TESTING
@@ -62,19 +69,19 @@ DEVELOPMENT, BUILDING, AND TESTING
   the modification fixes bugs :-)).
 
 - Add tests for new features. Extend test/timetest.c appropriately and
-  try to use the functional testing framework wherever possible. 
+  try to use the functional testing framework wherever possible.
 
 - Compiler and linker warnings are treated as errors and not acceptable.
 
-- If you cannot test the code on both Linux and OS X yourself, please 
-  let us know and consider wrapping your code in #ifdef / #ifndef __APPLE__ 
-  statements. 
+- If you cannot test the code on both Linux and macOS yourself, please
+  let us know and consider wrapping your code in #ifdef / #ifndef __APPLE__
+  statements.
 
 
 DOCUMENTATION
 =============
 
-For anything more than small bugfixes, please update the user documentation 
+For anything more than small bugfixes, please update the user documentation
 and credits appropriately:
 
 - The NEWS file should mention the change and your credits.
@@ -83,8 +90,8 @@ and credits appropriately:
 - The manpage man/faketime.1 should be updated when the wrapper application
   is modified.
 
-For credits, please either mention your real name, your Github username, or 
-your email address. 
+For credits, please either mention your real name, your Github username, or
+your email address.
 
 In your own interest, please be verbose on user documentation and comments
 in the source code. Users will not know about new features unless they are
@@ -97,7 +104,7 @@ RELEASES
 
 Official new releases are created whenever a significant amount of changes
 (bugfixes or new functionality) has piled up; on average, there is one new
-official release per year. Users who need to stick to the bleeding edge
+official release per 1-2 years. Users who need to stick to the bleeding edge
 are supposed to use the current state of the "master" branch at any time.
 
 libfaketime maintainers for several Linux distributions are informed about

TODO

@@ -1,10 +1,15 @@
-Open issues / next steps for libfaketime development
+Open issues / next steps for libfaketime development:
 
-- support interception of further system calls, e.g. clock_nanosleep (#105),
-  walltime (#195), chrono::system_clock::now (#176), select (#115)
+Please see the issue tracker on Github - https://github.com/wolfcw/libfaketime
+
+- New features, such as additional system calls to intercept, are labelled
+  "feature request" when they are considered for implementation
+
+- Issues labelled "help wanted" should be your starting point if you are
+  interested in contributing to libfaketime
+
+Besides the open issues, two major changes are planned for the next release:
 
-- fake timer_create and friends
-- add more functional tests that check more than the basic functionality
-- use the testing framework to also implement unit tests
-- work around thread local storage issue, e.g., by using pthreads
 - integrate manchicken's autoconf/automake support to get rid of separate Makefile.OSX
+
+- use the testing framework to also implement unit tests