rb-fsevent 0.9.3 → 0.9.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 73ff82cfa0945136952fd4b6f5d350de06023c02
+  data.tar.gz: c5b0b37f14237d9d9c3c3c75f07b78fd1729f397
+SHA512:
+  metadata.gz: 91a5b8a87e7dc4e8694100df01d027cbf182508dbd829ad38c3f63482ba489ea50f3f00c8757bc0d263ba203aa2584bfb2225d99d21d2c44f82e26dc9feadfa9
+  data.tar.gz: 736de2562e74149e3e0979d0da8b6ebe73d69b851dfbe2f5fd7eb9833919846159d75d330cb136ac685e0b019659c6f38810c52b1f9b224e2bc8a74c79282f45

data/.gitignore

@@ -0,0 +1,13 @@
+*.gem
+.DS_Store
+.Trashes
+.bundle
+.com.apple.timemachine.supported
+.fseventsd
+.idea
+.rbx
+/ext/build
+Desktop DB
+Desktop DF
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rake'
+

data/Guardfile

@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at http://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r(^spec/(.*)_spec.rb))
+  watch(%r(^lib/(.*)\.rb))        { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')    { 'spec' }
+end

data/{LICENSE → LICENSE.txt}

@@ -1,4 +1,6 @@
-Copyright (c) 2010-2012 Thibaud Guillaume-Gentil & Travis Tilley
+Copyright (c) 2010-2014 Thibaud Guillaume-Gentil & Travis Tilley
+
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,245 @@
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/thibaudgg/rb-fsevent)
+[![endorse](https://api.coderwall.com/ttilley/endorsecount.png)](https://coderwall.com/ttilley)
+
+# rb-fsevent
+
+Very simple & usable Mac OSX FSEvents API
+
+* RubyCocoa not required!
+* Signals are working (really)
+* Tested on MRI 1.8.7 & 1.9.3, RBX 2.0.0dev, JRuby
+* Tested on 10.6 -> 10.8 (though 10.5 should work just as well)
+
+## Install
+
+    gem install rb-fsevent
+
+### re-compilation
+
+rb-fsevent comes with a pre-compiled fsevent\_watch binary supporting x86\_64 and i386 on 10.6 and above. The binary is codesigned with my (Travis Tilley) Developer ID as an extra precaution when distributing pre-compiled code and contains an embedded plist describing its build environment. This should be sufficient for most users, but if you need to use rb-fsevent on 10.5 and/or on PPC then recompilation is necessary. This can be done by entering the installed gem's ext directory and running:
+
+    MACOSX_DEPLOYMENT_TARGET="10.5" CC=/usr/bin/gcc-4.2 rake ppc replace_exe
+
+The following ENV vars are recognized:
+
+* CC
+* CFLAGS
+* ARCHFLAGS
+* MACOSX\_DEPLOYMENT\_TARGET
+* FWDEBUG (enables debug mode, printing an obscene number of informational
+  messages to STDERR)
+
+### embedded plist
+
+You can retrieve the values in the embedded plist via the CLI:
+
+    fsevent_watch --show-plist
+
+The output is essentially formatted as `"#{key}:\n  #{value}\n"` to make it easier to read than plist style xml. The result looks like this:
+
+    DTSDKName:
+      macosx10.5
+    FSEWBuildTriple:
+      i386-apple-darwin10.8.0
+    FSEWCC:
+      /usr/bin/gcc-4.2
+    DTSDKPath:
+      /Developer/SDKs/MacOSX10.5.sdk
+    FSEWCCVersion:
+      i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5666) (dot 3)
+    FSEWCFLAGS:
+      -fconstant-cfstrings -fno-strict-aliasing -Wall -mmacosx-version-min=10.5 -O3
+
+If, for some perverse reason, you prefer to look at the xml... it can be retrieved via:
+
+    otool -s __TEXT __info_plist ./bin/fsevent_watch | grep ^0 | xxd -r -
+
+### codesign
+
+You can verify code signing information for a specific fsevent\_watch via:
+
+    codesign -d -vvv ./bin/fsevent_watch
+
+If you're using the pre-compiled binary, then the output should contain something to the effect of:
+
+    Authority=Developer ID Application: Travis Tilley
+    Authority=Developer ID Certification Authority
+    Authority=Apple Root CA
+    Timestamp=Dec 31, 2012 12:49:13 PM
+
+## Usage
+
+### Singular path
+
+```ruby
+require 'rb-fsevent'
+
+fsevent = FSEvent.new
+fsevent.watch Dir.pwd do |directories|
+  puts "Detected change inside: #{directories.inspect}"
+end
+fsevent.run
+```
+
+### Multiple paths
+
+```ruby
+require 'rb-fsevent'
+
+paths = ['/tmp/path/one', '/tmp/path/two', Dir.pwd]
+
+fsevent = FSEvent.new
+fsevent.watch paths do |directories|
+  puts "Detected change inside: #{directories.inspect}"
+end
+fsevent.run
+```
+
+### Multiple paths and additional options as a Hash
+
+```ruby
+require 'rb-fsevent'
+
+paths = ['/tmp/path/one', '/tmp/path/two', Dir.pwd]
+options = {:latency => 1.5, :no_defer => true }
+
+fsevent = FSEvent.new
+fsevent.watch paths, options do |directories|
+  puts "Detected change inside: #{directories.inspect}"
+end
+fsevent.run
+```
+
+### Multiple paths and additional options as an Array
+
+```ruby
+require 'rb-fsevent'
+
+paths = ['/tmp/path/one', '/tmp/path/two', Dir.pwd]
+options = ['--latency', 1.5, '--no-defer']
+
+fsevent = FSEvent.new
+fsevent.watch paths, options do |directories|
+  puts "Detected change inside: #{directories.inspect}"
+end
+fsevent.run
+```
+
+## Options
+
+When defining options using a hash or hash-like object, it gets checked for validity and converted to the appropriate fsevent\_watch commandline arguments array when the FSEvent class is instantiated. This is obviously the safest and preferred method of passing in options.
+
+You may, however, choose to pass in an array of commandline arguments as your options value and it will be passed on, unmodified, to the fsevent\_watch binary when called.
+
+So far, the following options are supported:
+
+* :latency => 0.5 # in seconds
+* :no\_defer => true
+* :watch\_root => true
+* :since\_when => 18446744073709551615 # an FSEventStreamEventId
+* :file\_events => true
+
+### Latency
+
+The :latency parameter determines how long the service should wait after the first event before passing that information along to the client. If your latency is set to 4 seconds, and 300 changes occur in the first three, then the callback will be fired only once. If latency is set to 0.1 in the exact same scenario, you will see that callback fire somewhere closer to between 25 and 30 times.
+
+Setting a higher latency value allows for more effective temporal coalescing, resulting in fewer callbacks and greater overall efficiency... at the cost of apparent responsiveness. Setting this to a reasonably high value (and NOT setting :no\_defer) is particularly well suited for background, daemon, or batch processing applications.
+
+Implementation note: It appears that FSEvents will only coalesce events from a maximum of 32 distinct subpaths, making the above completely accurate only when events are to fewer than 32 subpaths. Creating 300 files in one directory, for example, or 30 files in 10 subdirectories, but not 300 files within 300 subdirectories. In the latter case, you may receive 31 callbacks in one go after the latency period. As this appears to be an implementation detail, the number could potentially differ across OS revisions. It is entirely possible that this number is somehow configurable, but I have not yet discovered an accepted method of doing so.
+
+### NoDefer
+
+The :no\_defer option changes the behavior of the latency parameter completely. Rather than waiting for $latency period of time before sending along events in an attempt to coalesce a potential deluge ahead of time, that first event is sent along to the client immediately and is followed by a $latency period of silence before sending along any additional events that occurred within that period.
+
+This behavior is particularly useful for interactive applications where that feeling of apparent responsiveness is most important, but you still don't want to get overwhelmed by a series of events that occur in rapid succession.
+
+### WatchRoot
+
+The :watch\_root option allows for catching the scenario where you start watching "~/src/demo\_project" and either it is later renamed to "~/src/awesome\_sauce\_3000" or the path changes in such a manner that the original directory is now at "~/clients/foo/iteration4/demo\_project".
+
+Unfortunately, while this behavior is somewhat supported in the fsevent\_watch binary built as part of this project, support for passing across detailed metadata is not (yet). As a result, you would not receive the appropriate RootChanged event and be able to react appropriately. Also, since the C code doesn't open watched directories and retain that file descriptor as part of path-specific callback metadata, we are unable to issue an F\_GETPATH fcntl() to determine the directory's new path.
+
+Please do not use this option until proper support is added (or, even better, add it and submit a pull request).
+
+### SinceWhen
+
+The FSEventStreamEventId passed in to :since\_when is used as a base for reacting to historic events. Unfortunately, not only is the metadata for transitioning from historic to live events not currently passed along, but it is incorrectly passed as a change event on the root path, and only per-host event streams are currently supported. When using per-host event streams, the event IDs are not guaranteed to be unique or contiguous when shared volumes (firewire/USB/net/etc) are used on multiple macs.
+
+Please do not use this option until proper support is added, unless it's acceptable for you to receive that one fake event that's handled incorrectly when events transition from historical to live. Even in that scenario, there's no metadata available for determining the FSEventStreamEventId of the last received event.
+
+WARNING: passing in 0 as the parameter to :since\_when will return events for every directory modified since "the beginning of time".
+
+### FileEvents ###
+
+Prepare yourself for an obscene number of callbacks. Realistically, an "Atomic Save" could easily fire maybe 6 events for the combination of creating the new file, changing metadata/permissions, writing content, swapping out the old file for the new may itself result in multiple events being fired, and so forth. By the time you get the event for the temporary file being created as part of the atomic save, it will already be gone and swapped with the original file. This and issues of a similar nature have prevented me from adding the option to the ruby code despite the fsevent\_watch binary supporting file level events for quite some time now. Mountain Lion seems to be better at coalescing needless events, but that might just be my imagination.
+
+## Debugging output
+
+If the gem is re-compiled with the environment variable FWDEBUG set, then fsevent\_watch will be built with its various DEBUG sections defined, and the output to STDERR is truly verbose (and hopefully helpful in debugging your application and not just fsevent\_watch itself). If enough people find this to be directly useful when developing code that makes use of rb-fsevent, then it wouldn't be hard to clean this up and make it a feature enabled by a commandline argument instead. Until somebody files an issue, however, I will assume otherwise.
+
+    append_path called for: /tmp/moo/cow/
+      resolved path to: /private/tmp/moo/cow
+
+    config.sinceWhen    18446744073709551615
+    config.latency      0.300000
+    config.flags        00000000
+    config.paths
+      /private/tmp/moo/cow
+
+    FSEventStreamRef @ 0x100108540:
+       allocator = 0x7fff705a4ee0
+       callback = 0x10000151e
+       context = {0, 0x0, 0x0, 0x0, 0x0}
+       numPathsToWatch = 1
+       pathsToWatch = 0x7fff705a4ee0
+            pathsToWatch[0] = '/private/tmp/moo/cow'
+       latestEventId = -1
+       latency = 300000 (microseconds)
+       flags = 0x00000000
+       runLoop = 0x0
+       runLoopMode = 0x0
+
+    FSEventStreamCallback fired!
+      numEvents: 32
+      event path: /private/tmp/moo/cow/1/a/
+      event flags: 00000000
+      event ID: 1023767
+      event path: /private/tmp/moo/cow/1/b/
+      event flags: 00000000
+      event ID: 1023782
+      event path: /private/tmp/moo/cow/1/c/
+      event flags: 00000000
+      event ID: 1023797
+      event path: /private/tmp/moo/cow/1/d/
+      event flags: 00000000
+      event ID: 1023812
+      [etc]
+
+
+## Note about FFI
+
+rb-fsevent doesn't use [ruby-ffi](http://github.com/ffi/ffi) anymore because it sadly doesn't allow for catching Signals. You can still see the code in the [ffi branch](http://github.com/thibaudgg/rb-fsevent/tree/ffi).
+
+## Development
+
+* Source hosted at [GitHub](http://github.com/thibaudgg/rb-fsevent)
+* Report issues/Questions/Feature requests on [GitHub Issues](http://github.com/thibaudgg/rb-fsevent/issues)
+
+Pull requests are quite welcome! Please ensure that your commits are in a topic branch for each individual changeset that can be reasonably isolated. It is also important to ensure that your changes are well tested... whether that means new tests, modified tests, or fixing a scenario where the existing tests currently fail. If you have rbenv and ruby-build, we have a helper task for running the testsuite in all of them:
+
+    rake spec:portability
+
+The list of tested targets is currently:
+
+    %w[1.8.7-p371 1.9.3-p362 2.0.0-dev rbx-2.0.0-dev jruby-1.7.1]
+
+## Donations
+
+rb-fsevent is truly free software. The license is quite liberal (you don't even have to contribute back your changes). If, however, you'd like to donate as a way of showing support for the project and its continued development:
+
+[![Donate Bitcoins](https://d2o7j92jk8qjiw.cloudfront.net/assets/buttons/donation_small-2d08f8cd93c98acf496e0411cc6a5262.png)](https://coinbase.com/checkouts/5233986321e2217499bd6ef91f679aa4?c=rb-fsevent)
+    
+## Authors
+
+* [Travis Tilley](http://github.com/ttilley)
+* [Thibaud Guillaume-Gentil](http://github.com/thibaudgg)

data/Rakefile

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+
+namespace(:spec) do
+  desc "Run all specs on multiple ruby versions"
+  task(:portability) do
+    versions = %w[1.8.7-p371 1.9.3-p362 2.0.0-dev rbx-2.0.0-dev jruby-1.7.1]
+    versions.each do |version|
+      # system <<-BASH
+      #   bash -c 'source ~/.rvm/scripts/rvm;
+      #            rvm #{version};
+      #            echo "--------- version #{version} ----------\n";
+      #            bundle install;
+      #            rake spec'
+      # BASH
+      system <<-BASH
+        bash -c 'export PATH="$HOME/.rbenv/bin:$PATH";
+                 [[ `which rbenv` ]] && eval "$(rbenv init -)";
+                 [[ ! -a $HOME/.rbenv/versions/#{version} ]] && rbenv install #{version};
+                 rbenv shell #{version};
+                 rbenv which bundle 2> /dev/null || gem install bundler;
+                 bundle install;
+                 rake spec;'
+      BASH
+    end
+  end
+end

data/ext/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Travis Tilley
+Copyright (c) 2011-2013 Travis Tilley
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/ext/fsevent_watch/cli.c

@@ -6,6 +6,7 @@ const char* cli_info_usage = "Usage: fsevent_watch [OPTIONS]... [PATHS]...";
 const char* cli_info_help[] = {
   "  -h, --help                you're looking at it",
   "  -V, --version             print version number and exit",
+  "  -p, --show-plist          display the embedded Info.plist values",
   "  -s, --since-when=EventID  fire historical events since ID",
   "  -l, --latency=seconds     latency period (default='0.5')",
   "  -n, --no-defer            enable no-defer latency modifier",
@@ -25,6 +26,7 @@ static void default_args (struct cli_info* args_info)
   args_info->watch_root_flag    = false;
   args_info->ignore_self_flag   = false;
   args_info->file_events_flag   = false;
+  args_info->mark_self_flag     = false;
   args_info->format_arg         = kFSEventWatchOutputFormatClassic;
 }
 
@@ -56,12 +58,46 @@ void cli_parser_free (struct cli_info* args_info)
   cli_parser_release(args_info);
 }
 
+static void cli_print_info_dict (const void *key,
+                                 const void *value,
+                                 void *context)
+{
+  CFStringRef entry = CFStringCreateWithFormat(NULL, NULL,
+    CFSTR("%@:\n  %@"), key, value);
+  if (entry) {
+    CFShow(entry);
+    CFRelease(entry);
+  }
+}
+
+void cli_show_plist (void)
+{
+  CFBundleRef mainBundle = CFBundleGetMainBundle();
+  CFRetain(mainBundle);
+  CFDictionaryRef mainBundleDict = CFBundleGetInfoDictionary(mainBundle);
+  if (mainBundleDict) {
+    CFRetain(mainBundleDict);
+    printf("Embedded Info.plist metadata:\n\n");
+    CFDictionaryApplyFunction(mainBundleDict, cli_print_info_dict, NULL);
+    CFRelease(mainBundleDict);
+  }
+  CFRelease(mainBundle);
+  printf("\n");
+}
+
 void cli_print_version (void)
 {
-  printf("%s %s\n", CLI_NAME, CLI_VERSION);
+  printf("%s %s\n\n", CLI_NAME, CLI_VERSION);
 #ifdef COMPILED_AT
-  printf("Compiled %s\n", COMPILED_AT);
+  printf("Compiled at:    %s\n", COMPILED_AT);
+#endif
+#ifdef COMPILER
+  printf("Compiled with:  %s\n", COMPILER);
+#endif
+#ifdef TARGET_CPU
+  printf("Compiled for:   %s\n", TARGET_CPU);
 #endif
+  printf("\n");
 }
 
 void cli_print_help (void)
@@ -83,17 +119,19 @@ int cli_parser (int argc, const char** argv, struct cli_info* args_info)
   static struct option longopts[] = {
     { "help",         no_argument,        NULL, 'h' },
     { "version",      no_argument,        NULL, 'V' },
+    { "show-plist",   no_argument,        NULL, 'p' },
     { "since-when",   required_argument,  NULL, 's' },
     { "latency",      required_argument,  NULL, 'l' },
     { "no-defer",     no_argument,        NULL, 'n' },
     { "watch-root",   no_argument,        NULL, 'r' },
     { "ignore-self",  no_argument,        NULL, 'i' },
     { "file-events",  no_argument,        NULL, 'F' },
+    { "mark-self",    no_argument,        NULL, 'm' },
     { "format",       required_argument,  NULL, 'f' },
     { 0, 0, 0, 0 }
   };
 
-  const char* shortopts = "hVs:l:nriFf:";
+  const char* shortopts = "hVps:l:nriFf:";
 
   int c = -1;
 
@@ -117,6 +155,9 @@ int cli_parser (int argc, const char** argv, struct cli_info* args_info)
     case 'F': // file-events
       args_info->file_events_flag = true;
       break;
+    case 'm': // mark-self
+      args_info->mark_self_flag = true;
+      break;
     case 'f': // format
       if (strcmp(optarg, "classic") == 0) {
         args_info->format_arg = kFSEventWatchOutputFormatClassic;
@@ -134,6 +175,9 @@ int cli_parser (int argc, const char** argv, struct cli_info* args_info)
     case 'V': // version
       cli_print_version();
       exit(EXIT_SUCCESS);
+    case 'p': // show-plist
+      cli_show_plist();
+      exit(EXIT_SUCCESS);
     case 'h': // help
     case '?': // invalid option
     case ':': // missing argument

data/ext/fsevent_watch/cli.h

@@ -23,6 +23,7 @@ struct cli_info {
   bool watch_root_flag;
   bool ignore_self_flag;
   bool file_events_flag;
+  bool mark_self_flag;
   enum FSEventWatchOutputFormat format_arg;
 
   char** inputs;