From c60390a7e35c0161550c1bf022adfc0bb8fc9108 Mon Sep 17 00:00:00 2001 From: Wolfgang Hommel Date: Fri, 23 Aug 2019 15:24:13 +0200 Subject: [PATCH] Updated documentation regarding compatibility, use on macOS, and contributions --- README | 7 +++++++ README.OSX | 42 ++++++++++++++++++++++++++---------------- README.developers | 47 +++++++++++++++++++++++++++-------------------- TODO | 19 ++++++++++++------- 4 files changed, 72 insertions(+), 43 deletions(-) diff --git a/README b/README index b644a9f..25b5992 100644 --- a/README +++ b/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. diff --git a/README.OSX b/README.OSX index 7f17a63..00d14d4 100644 --- a/README.OSX +++ b/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,13 +129,20 @@ 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 @@ -141,4 +150,5 @@ feel free to report it. 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. diff --git a/README.developers b/README.developers index b8df57f..9c187a3 100644 --- a/README.developers +++ b/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 diff --git a/TODO b/TODO index aeda10d..490823d 100644 --- a/TODO +++ b/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