childprocess 0.8.0 → 3.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (50) hide show
  1. checksums.yaml +5 -5
  2. data/.document +6 -6
  3. data/.gitignore +28 -28
  4. data/.rspec +1 -1
  5. data/.travis.yml +40 -36
  6. data/CHANGELOG.md +73 -44
  7. data/Gemfile +21 -15
  8. data/LICENSE +20 -20
  9. data/README.md +218 -192
  10. data/Rakefile +61 -61
  11. data/appveyor.yml +42 -43
  12. data/childprocess.gemspec +26 -30
  13. data/lib/childprocess.rb +210 -205
  14. data/lib/childprocess/abstract_io.rb +36 -36
  15. data/lib/childprocess/abstract_process.rb +192 -192
  16. data/lib/childprocess/errors.rb +37 -26
  17. data/lib/childprocess/jruby.rb +56 -56
  18. data/lib/childprocess/jruby/io.rb +16 -16
  19. data/lib/childprocess/jruby/process.rb +184 -159
  20. data/lib/childprocess/jruby/pump.rb +53 -53
  21. data/lib/childprocess/tools/generator.rb +145 -145
  22. data/lib/childprocess/unix.rb +9 -9
  23. data/lib/childprocess/unix/fork_exec_process.rb +78 -70
  24. data/lib/childprocess/unix/io.rb +21 -21
  25. data/lib/childprocess/unix/lib.rb +186 -186
  26. data/lib/childprocess/unix/platform/i386-linux.rb +12 -12
  27. data/lib/childprocess/unix/platform/i386-solaris.rb +11 -11
  28. data/lib/childprocess/unix/platform/x86_64-linux.rb +12 -12
  29. data/lib/childprocess/unix/platform/x86_64-macosx.rb +11 -11
  30. data/lib/childprocess/unix/posix_spawn_process.rb +134 -134
  31. data/lib/childprocess/unix/process.rb +90 -89
  32. data/lib/childprocess/version.rb +3 -3
  33. data/lib/childprocess/windows.rb +38 -33
  34. data/lib/childprocess/windows/handle.rb +91 -91
  35. data/lib/childprocess/windows/io.rb +25 -25
  36. data/lib/childprocess/windows/lib.rb +416 -416
  37. data/lib/childprocess/windows/process.rb +130 -130
  38. data/lib/childprocess/windows/process_builder.rb +178 -175
  39. data/lib/childprocess/windows/structs.rb +148 -148
  40. data/spec/abstract_io_spec.rb +12 -12
  41. data/spec/childprocess_spec.rb +447 -391
  42. data/spec/get_env.ps1 +13 -0
  43. data/spec/io_spec.rb +228 -228
  44. data/spec/jruby_spec.rb +24 -24
  45. data/spec/pid_behavior.rb +12 -12
  46. data/spec/platform_detection_spec.rb +86 -86
  47. data/spec/spec_helper.rb +270 -261
  48. data/spec/unix_spec.rb +57 -57
  49. data/spec/windows_spec.rb +23 -23
  50. metadata +8 -39
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: fc6ebd5fca28a63f0cc66f1694f31961aa8dbd59
4
- data.tar.gz: 0a3a042ae2fa14dc9b70446553f296cedd4990f4
2
+ SHA256:
3
+ metadata.gz: b3927c01811510b0458e140f2b6f0fc6974f15ef733af515fa1d1b30976af4f4
4
+ data.tar.gz: 82883fa302f9e1698cff900a88cf5662e4561b5ca6fb5c6a794eccb65fc89d96
5
5
  SHA512:
6
- metadata.gz: 721fae3f6625d89823fcc87fbc2188d611cb4b0f120b26a7bd4ddc2c421d4791dc608dbfe90275a312a920d3620ec377e463d01a6b118bb3f2cf938230cd4f65
7
- data.tar.gz: 1a1f9e46433a97dc71e2937c6270f775d0c82db387daea194011eb83befde3e96912b83adbb472efbe03a381b7ac8a41e9009546c7157083f93c78738eeab6d6
6
+ metadata.gz: 98d6faa166068b1f9186cbf817ac5623e22212a7cd434b5a9213be80bf2e13df8d517513a772a5e5abf3a81c3dfe930c75bfd3f822423bf9e9259230dd4a26bd
7
+ data.tar.gz: 92082f9fb2ca7ec07bcaefcb1c0cd2619305204bbc7872090b485e694e36879e4de4d6abc460867a2715ea0214b0aeef16d67016fa0f36280028aa391b27ca94
data/.document CHANGED
@@ -1,6 +1,6 @@
1
- README.rdoc
2
- lib/**/*.rb
3
- bin/*
4
- features/**/*.feature
5
- -
6
- LICENSE
1
+ README.rdoc
2
+ lib/**/*.rb
3
+ bin/*
4
+ features/**/*.feature
5
+ -
6
+ LICENSE
data/.gitignore CHANGED
@@ -1,28 +1,28 @@
1
- ## MAC OS
2
- .DS_Store
3
-
4
- ## TEXTMATE
5
- *.tmproj
6
- tmtags
7
-
8
- ## EMACS
9
- *~
10
- \#*
11
- .\#*
12
-
13
- ## VIM
14
- *.swp
15
-
16
- ## RubyMine
17
- .idea/*
18
-
19
- ## PROJECT::GENERAL
20
- coverage
21
- rdoc
22
- pkg
23
- .rbx
24
- Gemfile.lock
25
- .ruby-version
26
- .bundle
27
-
28
- ## PROJECT::SPECIFIC
1
+ ## MAC OS
2
+ .DS_Store
3
+
4
+ ## TEXTMATE
5
+ *.tmproj
6
+ tmtags
7
+
8
+ ## EMACS
9
+ *~
10
+ \#*
11
+ .\#*
12
+
13
+ ## VIM
14
+ *.swp
15
+
16
+ ## RubyMine
17
+ .idea/*
18
+
19
+ ## PROJECT::GENERAL
20
+ coverage
21
+ rdoc
22
+ pkg
23
+ .rbx
24
+ Gemfile.lock
25
+ .ruby-version
26
+ .bundle
27
+
28
+ ## PROJECT::SPECIFIC
data/.rspec CHANGED
@@ -1 +1 @@
1
- --color
1
+ --color
@@ -1,36 +1,40 @@
1
- os:
2
- - linux
3
- - osx
4
-
5
- rvm:
6
- - 1.9.3
7
- - jruby-9.1.9.0
8
- - rbx-3
9
- - 2.0.0
10
- - 2.1
11
- - 2.2
12
- - 2.3.5
13
- - 2.4.0
14
- - ruby-head
15
-
16
- sudo: true # Necessary to fix JRuby
17
-
18
- cache: bundler
19
-
20
- before_install:
21
- - "echo 'gem: --no-document' > ~/.gemrc"
22
- - gem update --system
23
- - gem install bundler # Necessary to fix 1.9.3
24
-
25
- env:
26
- global:
27
- matrix:
28
- - CHILDPROCESS_POSIX_SPAWN=true CHILDPROCESS_UNSET=should-be-unset
29
- - CHILDPROCESS_POSIX_SPAWN=false CHILDPROCESS_UNSET=should-be-unset
30
-
31
- matrix:
32
- allow_failures:
33
- - rvm: rbx-3
34
- - rvm: jruby-9.1.9.0
35
- - rvm: ruby-head
36
- - env: "CHILDPROCESS_POSIX_SPAWN=true"
1
+ os:
2
+ - linux
3
+ - osx
4
+
5
+ rvm:
6
+ - rbx-3
7
+ - 2.3
8
+ - 2.4
9
+ - 2.5
10
+ - 2.6
11
+ - ruby-head
12
+
13
+ sudo: false
14
+
15
+ cache: bundler
16
+
17
+ before_install:
18
+ - "echo 'gem: --no-document' > ~/.gemrc"
19
+ # RubyGems update is supported for Ruby 2.3 and later
20
+ - ruby -e "system('gem update --system') if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.3')"
21
+ - gem install bundler --version '~> 1.17'
22
+
23
+ before_script:
24
+ - 'export JAVA_OPTS="${JAVA_OPTS_FOR_SPECS}"'
25
+
26
+ env:
27
+ global:
28
+ matrix:
29
+ - CHILDPROCESS_POSIX_SPAWN=true CHILDPROCESS_UNSET=should-be-unset
30
+ - CHILDPROCESS_POSIX_SPAWN=false CHILDPROCESS_UNSET=should-be-unset
31
+
32
+ matrix:
33
+ allow_failures:
34
+ - rvm: rbx-3
35
+ - rvm: ruby-head
36
+ - env: "CHILDPROCESS_POSIX_SPAWN=true"
37
+ include:
38
+ - rvm: jruby-9.2.5.0
39
+ jdk: openjdk11
40
+ env: "JAVA_OPTS_FOR_SPECS='--add-opens java.base/java.io=org.jruby.dist --add-opens java.base/sun.nio.ch=org.jruby.dist'"
@@ -1,44 +1,73 @@
1
- ### Version 0.8.0 / 2017-09-23
2
-
3
- * Added a method for determining whether or nto a process had been started.
4
-
5
-
6
- ### Version 0.7.1 / 2017-06-26
7
-
8
- * Fixed a noisy uninitialized variable warning
9
-
10
-
11
- ### Version 0.7.0 / 2017-05-07
12
-
13
- * Debugging information now uses a Logger, which can be configured.
14
-
15
-
16
- ### Version 0.6.3 / 2017-03-24
17
-
18
- See beta release notes.
19
-
20
-
21
- ### Version 0.6.3.beta.1 / 2017-03-10
22
-
23
- * Bug fix: Fixed child process creation problems on Windows 7 when a child was declared as a leader.
24
-
25
-
26
- ### Version 0.6.2 / 2017-02-25
27
-
28
- * Bug fix: Fixed a potentially broken edge case that could occur on older 32-bit OSX systems.
29
-
30
-
31
- ### Version 0.6.1 / 2017-01-22
32
-
33
- * Bug fix: Fixed a dependency that was accidentally declared as a runtime
34
- dependency instead of a development dependency.
35
-
36
-
37
- ### Version 0.6.0 / 2017-01-22
38
-
39
- * Support for Ruby 2.4 added
40
-
41
-
42
- ### Version 0.5.9 / 2016-01-06
43
-
44
- * The Great Before Times...
1
+ ### Version 3.0.0 / 2019-09-20
2
+
3
+ * [#156](https://github.com/enkessler/childprocess/pull/156)Remove unused `rubyforge_project` from gemspec
4
+ * [#160](https://github.com/enkessler/childprocess/pull/160): Remove extension to conditionally install `ffi` gem on Windows platforms
5
+ * [#160](https://github.com/enkessler/childprocess/pull/160): Remove runtime dependency on `rake` gem
6
+
7
+ ### Version 2.0.0 / 2019-07-11
8
+
9
+ * [#148](https://github.com/enkessler/childprocess/pull/148): Drop support for Ruby 2.0, 2.1, and 2.2
10
+ * [#149](https://github.com/enkessler/childprocess/pull/149): Fix Unix fork reopen to be compatible with Ruby 2.6
11
+ * [#152](https://github.com/enkessler/childprocess/pull/152)/[#154](https://github.com/enkessler/childprocess/pull/154): Fix hangs and permission errors introduced in Ruby 2.6 for leader processes of process groups
12
+
13
+ ### Version 1.0.1 / 2019-02-03
14
+
15
+ * [#143](https://github.com/enkessler/childprocess/pull/144): Fix installs by adding `rake` gem as runtime dependency
16
+ * [#147](https://github.com/enkessler/childprocess/pull/147): Relax `rake` gem constraint from `< 12` to `< 13`
17
+
18
+ ### Version 1.0.0 / 2019-01-28
19
+
20
+ * [#134](https://github.com/enkessler/childprocess/pull/134): Add support for non-ASCII characters on Windows
21
+ * [#132](https://github.com/enkessler/childprocess/pull/132): Install `ffi` gem requirement on Windows only
22
+ * [#128](https://github.com/enkessler/childprocess/issues/128): Convert environment variable values to strings when `posix_spawn` enabled
23
+ * [#141](https://github.com/enkessler/childprocess/pull/141): Support JRuby on Java >= 9
24
+
25
+ ### Version 0.9.0 / 2018-03-10
26
+
27
+ * Added support for DragonFly BSD.
28
+
29
+
30
+ ### Version 0.8.0 / 2017-09-23
31
+
32
+ * Added a method for determining whether or not a process had been started.
33
+
34
+
35
+ ### Version 0.7.1 / 2017-06-26
36
+
37
+ * Fixed a noisy uninitialized variable warning
38
+
39
+
40
+ ### Version 0.7.0 / 2017-05-07
41
+
42
+ * Debugging information now uses a Logger, which can be configured.
43
+
44
+
45
+ ### Version 0.6.3 / 2017-03-24
46
+
47
+ See beta release notes.
48
+
49
+
50
+ ### Version 0.6.3.beta.1 / 2017-03-10
51
+
52
+ * Bug fix: Fixed child process creation problems on Windows 7 when a child was declared as a leader.
53
+
54
+
55
+ ### Version 0.6.2 / 2017-02-25
56
+
57
+ * Bug fix: Fixed a potentially broken edge case that could occur on older 32-bit OSX systems.
58
+
59
+
60
+ ### Version 0.6.1 / 2017-01-22
61
+
62
+ * Bug fix: Fixed a dependency that was accidentally declared as a runtime
63
+ dependency instead of a development dependency.
64
+
65
+
66
+ ### Version 0.6.0 / 2017-01-22
67
+
68
+ * Support for Ruby 2.4 added
69
+
70
+
71
+ ### Version 0.5.9 / 2016-01-06
72
+
73
+ * The Great Before Times...
data/Gemfile CHANGED
@@ -1,15 +1,21 @@
1
- source "http://rubygems.org"
2
-
3
- # Specify your gem's dependencies in child_process.gemspec
4
- gemspec
5
-
6
-
7
- if RUBY_VERSION =~ /^1\./
8
- gem 'tins', '< 1.7' # The 'tins' gem requires Ruby 2.x on/after this version
9
- gem 'json', '< 2.0' # The 'json' gem drops pre-Ruby 2.x support on/after this version
10
- gem 'term-ansicolor', '< 1.4' # The 'term-ansicolor' gem requires Ruby 2.x on/after this version
11
-
12
- if RbConfig::CONFIG['host_os'].downcase =~ /mswin|msys|mingw32/
13
- gem 'ffi', '< 1.9.15' # The 'ffi' gem, for Windows, requires Ruby 2.x on/after this version
14
- end
15
- end
1
+ source 'http://rubygems.org'
2
+
3
+ # Specify your gem's dependencies in child_process.gemspec
4
+ gemspec
5
+
6
+ # Used for local development/testing only
7
+ gem 'rake'
8
+
9
+ if RUBY_VERSION =~ /^1\./
10
+ gem 'tins', '< 1.7' # The 'tins' gem requires Ruby 2.x on/after this version
11
+ gem 'json', '< 2.0' # The 'json' gem drops pre-Ruby 2.x support on/after this version
12
+ gem 'term-ansicolor', '< 1.4' # The 'term-ansicolor' gem requires Ruby 2.x on/after this version
13
+
14
+ # ffi gem for Windows requires Ruby 2.x on/after this version
15
+ gem 'ffi', '< 1.9.15' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
16
+ elsif Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.2')
17
+ # Ruby 2.0/2.1 support only ffi before 1.10
18
+ gem 'ffi', '~> 1.9.0' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
19
+ else
20
+ gem 'ffi' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
21
+ end
data/LICENSE CHANGED
@@ -1,20 +1,20 @@
1
- Copyright (c) 2010-2015 Jari Bakken
2
-
3
- Permission is hereby granted, free of charge, to any person obtaining
4
- a copy of this software and associated documentation files (the
5
- "Software"), to deal in the Software without restriction, including
6
- without limitation the rights to use, copy, modify, merge, publish,
7
- distribute, sublicense, and/or sell copies of the Software, and to
8
- permit persons to whom the Software is furnished to do so, subject to
9
- the following conditions:
10
-
11
- The above copyright notice and this permission notice shall be
12
- included in all copies or substantial portions of the Software.
13
-
14
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1
+ Copyright (c) 2010-2015 Jari Bakken
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md CHANGED
@@ -1,192 +1,218 @@
1
- # childprocess
2
-
3
- This gem aims at being a simple and reliable solution for controlling
4
- external programs running in the background on any Ruby / OS combination.
5
-
6
- The code originated in the [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver) gem, but should prove useful as
7
- a standalone library.
8
-
9
- [![Build Status](https://secure.travis-ci.org/enkessler/childprocess.svg)](http://travis-ci.org/enkessler/childprocess)
10
- [![Build status](https://ci.appveyor.com/api/projects/status/fn2snbcd7kku5myk/branch/dev?svg=true)](https://ci.appveyor.com/project/enkessler/childprocess/branch/dev)
11
- [![Gem Version](https://badge.fury.io/rb/childprocess.svg)](http://badge.fury.io/rb/childprocess)
12
- [![Code Climate](https://codeclimate.com/github/enkessler/childprocess.svg)](https://codeclimate.com/github/enkessler/childprocess)
13
- [![Coverage Status](https://coveralls.io/repos/enkessler/childprocess/badge.svg?branch=master)](https://coveralls.io/r/enkessler/childprocess?branch=master)
14
-
15
- # Usage
16
-
17
- The object returned from `ChildProcess.build` will implement `ChildProcess::AbstractProcess`.
18
-
19
- ### Basic examples
20
-
21
- ```ruby
22
- process = ChildProcess.build("ruby", "-e", "sleep")
23
-
24
- # inherit stdout/stderr from parent...
25
- process.io.inherit!
26
-
27
- # ...or pass an IO
28
- process.io.stdout = Tempfile.new("child-output")
29
-
30
- # modify the environment for the child
31
- process.environment["a"] = "b"
32
- process.environment["c"] = nil
33
-
34
- # set the child's working directory
35
- process.cwd = '/some/path'
36
-
37
- # start the process
38
- process.start
39
-
40
- # check process status
41
- process.alive? #=> true
42
- process.exited? #=> false
43
-
44
- # wait indefinitely for process to exit...
45
- process.wait
46
- process.exited? #=> true
47
-
48
- # get the exit code
49
- process.exit_code #=> 0
50
-
51
- # ...or poll for exit + force quit
52
- begin
53
- process.poll_for_exit(10)
54
- rescue ChildProcess::TimeoutError
55
- process.stop # tries increasingly harsher methods to kill the process.
56
- end
57
- ```
58
-
59
- ### Advanced examples
60
-
61
- #### Output to pipe
62
-
63
- ```ruby
64
- r, w = IO.pipe
65
-
66
- proc = ChildProcess.build("echo", "foo")
67
- proc.io.stdout = proc.io.stderr = w
68
- proc.start
69
- w.close
70
-
71
- begin
72
- loop { print r.readpartial(8192) }
73
- rescue EOFError
74
- end
75
-
76
- proc.wait
77
- ```
78
-
79
- Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
80
-
81
- #### Write to stdin
82
-
83
- ```ruby
84
- process = ChildProcess.build("cat")
85
-
86
- out = Tempfile.new("duplex")
87
- out.sync = true
88
-
89
- process.io.stdout = process.io.stderr = out
90
- process.duplex = true # sets up pipe so process.io.stdin will be available after .start
91
-
92
- process.start
93
- process.io.stdin.puts "hello world"
94
- process.io.stdin.close
95
-
96
- process.poll_for_exit(exit_timeout_in_seconds)
97
-
98
- out.rewind
99
- out.read #=> "hello world\n"
100
- ```
101
-
102
- #### Pipe output to another ChildProcess
103
-
104
- ```ruby
105
- search = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
106
- search.duplex = true # sets up pipe so search.io.stdin will be available after .start
107
- search.io.stdout = $stdout
108
- search.start
109
-
110
- listing = ChildProcess.build("ps", "aux")
111
- listing.io.stdout = search.io.stdin
112
- listing.start
113
- listing.wait
114
-
115
- search.io.stdin.close
116
- search.wait
117
- ```
118
-
119
- #### Prefer posix_spawn on *nix
120
-
121
- If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
122
-
123
- ```ruby
124
- ChildProcess.posix_spawn = true
125
- process = ChildProcess.build(*args)
126
- ```
127
-
128
- ### Ensure entire process tree dies
129
-
130
- By default, the child process does not create a new process group. This means there's no guarantee that the entire process tree will die when the child process is killed. To solve this:
131
-
132
- ```ruby
133
- process = ChildProcess.build(*args)
134
- process.leader = true
135
- process.start
136
- ```
137
-
138
- #### Detach from parent
139
-
140
- ```ruby
141
- process = ChildProcess.build("sleep", "10")
142
- process.detach = true
143
- process.start
144
- ```
145
-
146
- #### Invoking a shell
147
-
148
- As opposed to `Kernel#system`, `Kernel#exec` et al., ChildProcess will not automatically execute your command in a shell (like `/bin/sh` or `cmd.exe`) depending on the arguments.
149
- This means that if you try to execute e.g. gem executables (like `bundle` or `gem`) or Windows executables (with `.com` or `.bat` extensions) you may see a `ChildProcess::LaunchError`.
150
- You can work around this by being explicit about what interpreter to invoke:
151
-
152
- ```ruby
153
- ChildProcess.build("cmd.exe", "/c", "bundle")
154
- ChildProcess.build("ruby", "-S", "bundle")
155
- ```
156
-
157
- #### Log to file
158
-
159
- Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead.
160
-
161
- ```ruby
162
- logger = Logger.new('logfile.log')
163
- logger.level = Logger::DEBUG
164
- ChildProcess.logger = logger
165
- ```
166
-
167
- ## Caveats
168
-
169
- * With JRuby on Unix, modifying `ENV["PATH"]` before using childprocess could lead to 'Command not found' errors, since JRuby is unable to modify the environemnt used for PATH searches in `java.lang.ProcessBuilder`. This can be avoided by setting `ChildProcess.posix_spawn = true`.
170
-
171
- # Implementation
172
-
173
- How the process is launched and killed depends on the platform:
174
-
175
- * Unix : `fork + exec` (or `posix_spawn` if enabled)
176
- * Windows : `CreateProcess()` and friends
177
- * JRuby : `java.lang.{Process,ProcessBuilder}`
178
-
179
- # Note on Patches/Pull Requests
180
-
181
- 1. Fork it
182
- 2. Create your feature branch (off of the development branch)
183
- `git checkout -b my-new-feature dev`
184
- 3. Commit your changes
185
- `git commit -am 'Add some feature'`
186
- 4. Push to the branch
187
- `git push origin my-new-feature`
188
- 5. Create new Pull Request
189
-
190
- # Copyright
191
-
192
- Copyright (c) 2010-2015 Jari Bakken. See LICENSE for details.
1
+ # childprocess
2
+
3
+ This gem aims at being a simple and reliable solution for controlling
4
+ external programs running in the background on any Ruby / OS combination.
5
+
6
+ The code originated in the [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver) gem, but should prove useful as
7
+ a standalone library.
8
+
9
+ [![Build Status](https://secure.travis-ci.org/enkessler/childprocess.svg)](http://travis-ci.org/enkessler/childprocess)
10
+ [![Build status](https://ci.appveyor.com/api/projects/status/fn2snbcd7kku5myk/branch/dev?svg=true)](https://ci.appveyor.com/project/enkessler/childprocess/branch/dev)
11
+ [![Gem Version](https://badge.fury.io/rb/childprocess.svg)](http://badge.fury.io/rb/childprocess)
12
+ [![Code Climate](https://codeclimate.com/github/enkessler/childprocess.svg)](https://codeclimate.com/github/enkessler/childprocess)
13
+ [![Coverage Status](https://coveralls.io/repos/enkessler/childprocess/badge.svg?branch=master)](https://coveralls.io/r/enkessler/childprocess?branch=master)
14
+
15
+ # Requirements
16
+
17
+ * Ruby 2.3+, JRuby 9+
18
+
19
+ Windows users **must** ensure the `ffi` gem (`>= 1.0.11`) is installed in order to use ChildProcess.
20
+
21
+ # Usage
22
+
23
+ The object returned from `ChildProcess.build` will implement `ChildProcess::AbstractProcess`.
24
+
25
+ ### Basic examples
26
+
27
+ ```ruby
28
+ process = ChildProcess.build("ruby", "-e", "sleep")
29
+
30
+ # inherit stdout/stderr from parent...
31
+ process.io.inherit!
32
+
33
+ # ...or pass an IO
34
+ process.io.stdout = Tempfile.new("child-output")
35
+
36
+ # modify the environment for the child
37
+ process.environment["a"] = "b"
38
+ process.environment["c"] = nil
39
+
40
+ # set the child's working directory
41
+ process.cwd = '/some/path'
42
+
43
+ # start the process
44
+ process.start
45
+
46
+ # check process status
47
+ process.alive? #=> true
48
+ process.exited? #=> false
49
+
50
+ # wait indefinitely for process to exit...
51
+ process.wait
52
+ process.exited? #=> true
53
+
54
+ # get the exit code
55
+ process.exit_code #=> 0
56
+
57
+ # ...or poll for exit + force quit
58
+ begin
59
+ process.poll_for_exit(10)
60
+ rescue ChildProcess::TimeoutError
61
+ process.stop # tries increasingly harsher methods to kill the process.
62
+ end
63
+ ```
64
+
65
+ ### Advanced examples
66
+
67
+ #### Output to pipe
68
+
69
+ ```ruby
70
+ r, w = IO.pipe
71
+
72
+ proc = ChildProcess.build("echo", "foo")
73
+ proc.io.stdout = proc.io.stderr = w
74
+ proc.start
75
+
76
+ Thread.new {
77
+ begin
78
+ loop do
79
+ print r.readpartial(8192)
80
+ end
81
+ rescue EOFError
82
+ end
83
+ }
84
+
85
+ proc.wait
86
+ w.close
87
+ ```
88
+
89
+ Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
90
+
91
+ #### Write to stdin
92
+
93
+ ```ruby
94
+ process = ChildProcess.build("cat")
95
+
96
+ out = Tempfile.new("duplex")
97
+ out.sync = true
98
+
99
+ process.io.stdout = process.io.stderr = out
100
+ process.duplex = true # sets up pipe so process.io.stdin will be available after .start
101
+
102
+ process.start
103
+ process.io.stdin.puts "hello world"
104
+ process.io.stdin.close
105
+
106
+ process.poll_for_exit(exit_timeout_in_seconds)
107
+
108
+ out.rewind
109
+ out.read #=> "hello world\n"
110
+ ```
111
+
112
+ #### Pipe output to another ChildProcess
113
+
114
+ ```ruby
115
+ search = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
116
+ search.duplex = true # sets up pipe so search.io.stdin will be available after .start
117
+ search.io.stdout = $stdout
118
+ search.start
119
+
120
+ listing = ChildProcess.build("ps", "aux")
121
+ listing.io.stdout = search.io.stdin
122
+ listing.start
123
+ listing.wait
124
+
125
+ search.io.stdin.close
126
+ search.wait
127
+ ```
128
+
129
+ #### Prefer posix_spawn on *nix
130
+
131
+ If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
132
+
133
+ ```ruby
134
+ ChildProcess.posix_spawn = true
135
+ process = ChildProcess.build(*args)
136
+ ```
137
+
138
+ To be able to use this, please make sure that you have the `ffi` gem installed.
139
+
140
+ ### Ensure entire process tree dies
141
+
142
+ By default, the child process does not create a new process group. This means there's no guarantee that the entire process tree will die when the child process is killed. To solve this:
143
+
144
+ ```ruby
145
+ process = ChildProcess.build(*args)
146
+ process.leader = true
147
+ process.start
148
+ ```
149
+
150
+ #### Detach from parent
151
+
152
+ ```ruby
153
+ process = ChildProcess.build("sleep", "10")
154
+ process.detach = true
155
+ process.start
156
+ ```
157
+
158
+ #### Invoking a shell
159
+
160
+ As opposed to `Kernel#system`, `Kernel#exec` et al., ChildProcess will not automatically execute your command in a shell (like `/bin/sh` or `cmd.exe`) depending on the arguments.
161
+ This means that if you try to execute e.g. gem executables (like `bundle` or `gem`) or Windows executables (with `.com` or `.bat` extensions) you may see a `ChildProcess::LaunchError`.
162
+ You can work around this by being explicit about what interpreter to invoke:
163
+
164
+ ```ruby
165
+ ChildProcess.build("cmd.exe", "/c", "bundle")
166
+ ChildProcess.build("ruby", "-S", "bundle")
167
+ ```
168
+
169
+ #### Log to file
170
+
171
+ Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead.
172
+
173
+ ```ruby
174
+ logger = Logger.new('logfile.log')
175
+ logger.level = Logger::DEBUG
176
+ ChildProcess.logger = logger
177
+ ```
178
+
179
+ ## Caveats
180
+
181
+ * With JRuby on Unix, modifying `ENV["PATH"]` before using childprocess could lead to 'Command not found' errors, since JRuby is unable to modify the environment used for PATH searches in `java.lang.ProcessBuilder`. This can be avoided by setting `ChildProcess.posix_spawn = true`.
182
+ * With JRuby on Java >= 9, the JVM may need to be configured to allow JRuby to access neccessary implementations; this can be done by adding `--add-opens java.base/java.io=org.jruby.dist` and `--add-opens java.base/sun.nio.ch=org.jruby.dist` to the `JAVA_OPTS` environment variable that is used by JRuby when launching the JVM.
183
+
184
+ # Implementation
185
+
186
+ How the process is launched and killed depends on the platform:
187
+
188
+ * Unix : `fork + exec` (or `posix_spawn` if enabled)
189
+ * Windows : `CreateProcess()` and friends
190
+ * JRuby : `java.lang.{Process,ProcessBuilder}`
191
+
192
+ # Note on Patches/Pull Requests
193
+
194
+ 1. Fork it
195
+ 2. Create your feature branch (off of the development branch)
196
+ `git checkout -b my-new-feature dev`
197
+ 3. Commit your changes
198
+ `git commit -am 'Add some feature'`
199
+ 4. Push to the branch
200
+ `git push origin my-new-feature`
201
+ 5. Create new Pull Request
202
+
203
+ # Publishing a New Release
204
+
205
+ When publishing a new gem release:
206
+
207
+ 1. Ensure [latest build is green on the `dev` branch](https://travis-ci.org/enkessler/childprocess/branches)
208
+ 2. Ensure [CHANGELOG](CHANGELOG.md) is updated
209
+ 3. Ensure [version is bumped](lib/childprocess/version.rb) following [Semantic Versioning](https://semver.org/)
210
+ 4. Merge the `dev` branch into `master`: `git checkout master && git merge dev`
211
+ 5. Ensure [latest build is green on the `master` branch](https://travis-ci.org/enkessler/childprocess/branches)
212
+ 6. Build gem from the green `master` branch: `git checkout master && gem build childprocess.gemspec`
213
+ 7. Push gem to RubyGems: `gem push childprocess-<VERSION>.gem`
214
+ 8. Tag commit with version, annotated with release notes: `git tag -a <VERSION>`
215
+
216
+ # Copyright
217
+
218
+ Copyright (c) 2010-2015 Jari Bakken. See [LICENSE](LICENSE) for details.