1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
# childprocess
This gem aims at being a simple and reliable solution for controlling
external programs running in the background on any Ruby / OS combination.
The code originated in the [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver) gem, but should prove useful as
a standalone library.
[](http://travis-ci.org/enkessler/childprocess)
[](https://ci.appveyor.com/project/enkessler/childprocess/branch/dev)
[](http://badge.fury.io/rb/childprocess)
[](https://codeclimate.com/github/enkessler/childprocess)
[](https://coveralls.io/r/enkessler/childprocess?branch=master)
# Requirements
* Ruby 2.4+, JRuby 9+
Windows users **must** ensure the `ffi` gem (`>= 1.0.11`) is installed in order to use ChildProcess.
# Usage
The object returned from `ChildProcess.build` will implement `ChildProcess::AbstractProcess`.
### Basic examples
```ruby
process = ChildProcess.build("ruby", "-e", "sleep")
# inherit stdout/stderr from parent...
process.io.inherit!
# ...or pass an IO
process.io.stdout = Tempfile.new("child-output")
# modify the environment for the child
process.environment["a"] = "b"
process.environment["c"] = nil
# set the child's working directory
process.cwd = '/some/path'
# start the process
process.start
# check process status
process.alive? #=> true
process.exited? #=> false
# wait indefinitely for process to exit...
process.wait
process.exited? #=> true
# get the exit code
process.exit_code #=> 0
# ...or poll for exit + force quit
begin
process.poll_for_exit(10)
rescue ChildProcess::TimeoutError
process.stop # tries increasingly harsher methods to kill the process.
end
```
### Advanced examples
#### Output to pipe
```ruby
r, w = IO.pipe
begin
process = ChildProcess.build("sh" , "-c",
"for i in {1..3}; do echo $i; sleep 1; done")
process.io.stdout = w
process.start # This results in a fork, inheriting the write end of the pipe.
# Close parent's copy of the write end of the pipe so when the (forked) child
# process closes its write end of the pipe the parent receives EOF when
# attempting to read from it. If the parent leaves its write end open, it
# will not detect EOF.
w.close
thread = Thread.new do
begin
loop do
print r.readpartial(16384)
end
rescue EOFError
# Child has closed the write end of the pipe
end
end
process.wait
thread.join
ensure
r.close
end
```
Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
#### Write to stdin
```ruby
process = ChildProcess.build("cat")
out = Tempfile.new("duplex")
out.sync = true
process.io.stdout = process.io.stderr = out
process.duplex = true # sets up pipe so process.io.stdin will be available after .start
process.start
process.io.stdin.puts "hello world"
process.io.stdin.close
process.poll_for_exit(exit_timeout_in_seconds)
out.rewind
out.read #=> "hello world\n"
```
#### Pipe output to another ChildProcess
```ruby
search = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
search.duplex = true # sets up pipe so search.io.stdin will be available after .start
search.io.stdout = $stdout
search.start
listing = ChildProcess.build("ps", "aux")
listing.io.stdout = search.io.stdin
listing.start
listing.wait
search.io.stdin.close
search.wait
```
#### Prefer posix_spawn on *nix
If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
```ruby
ChildProcess.posix_spawn = true
process = ChildProcess.build(*args)
```
To be able to use this, please make sure that you have the `ffi` gem installed.
### Ensure entire process tree dies
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:
```ruby
process = ChildProcess.build(*args)
process.leader = true
process.start
```
#### Detach from parent
```ruby
process = ChildProcess.build("sleep", "10")
process.detach = true
process.start
```
#### Invoking a shell
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.
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`.
You can work around this by being explicit about what interpreter to invoke:
```ruby
ChildProcess.build("cmd.exe", "/c", "bundle")
ChildProcess.build("ruby", "-S", "bundle")
```
#### Log to file
Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead.
```ruby
logger = Logger.new('logfile.log')
logger.level = Logger::DEBUG
ChildProcess.logger = logger
```
## Caveats
* 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`.
* 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.
# Implementation
How the process is launched and killed depends on the platform:
* Unix : `fork + exec` (or `posix_spawn` if enabled)
* Windows : `CreateProcess()` and friends
* JRuby : `java.lang.{Process,ProcessBuilder}`
# Note on Patches/Pull Requests
1. Fork it
2. Create your feature branch (off of the development branch)
`git checkout -b my-new-feature dev`
3. Commit your changes
`git commit -am 'Add some feature'`
4. Push to the branch
`git push origin my-new-feature`
5. Create new Pull Request
# Publishing a New Release
When publishing a new gem release:
1. Ensure [latest build is green on the `dev` branch](https://travis-ci.org/enkessler/childprocess/branches)
2. Ensure [CHANGELOG](CHANGELOG.md) is updated
3. Ensure [version is bumped](lib/childprocess/version.rb) following [Semantic Versioning](https://semver.org/)
4. Merge the `dev` branch into `master`: `git checkout master && git merge dev`
5. Ensure [latest build is green on the `master` branch](https://travis-ci.org/enkessler/childprocess/branches)
6. Build gem from the green `master` branch: `git checkout master && gem build childprocess.gemspec`
7. Push gem to RubyGems: `gem push childprocess-<VERSION>.gem`
8. Tag commit with version, annotated with release notes: `git tag -a <VERSION>`
# Copyright
Copyright (c) 2010-2015 Jari Bakken. See [LICENSE](LICENSE) for details.
|
