childprocess 0.9.0 → 4.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/.document +6 -6
- data/.gitignore +28 -28
- data/.rspec +1 -1
- data/.travis.yml +37 -44
- data/CHANGELOG.md +77 -49
- data/Gemfile +21 -15
- data/LICENSE +20 -20
- data/README.md +230 -196
- data/Rakefile +61 -61
- data/appveyor.yml +36 -60
- data/childprocess.gemspec +26 -30
- data/lib/childprocess.rb +210 -205
- data/lib/childprocess/abstract_io.rb +36 -36
- data/lib/childprocess/abstract_process.rb +192 -192
- data/lib/childprocess/errors.rb +37 -26
- data/lib/childprocess/jruby.rb +56 -56
- data/lib/childprocess/jruby/io.rb +16 -16
- data/lib/childprocess/jruby/process.rb +184 -159
- data/lib/childprocess/jruby/pump.rb +53 -53
- data/lib/childprocess/tools/generator.rb +145 -145
- data/lib/childprocess/unix.rb +9 -9
- data/lib/childprocess/unix/fork_exec_process.rb +78 -70
- data/lib/childprocess/unix/io.rb +21 -21
- data/lib/childprocess/unix/lib.rb +186 -186
- data/lib/childprocess/unix/platform/i386-linux.rb +12 -12
- data/lib/childprocess/unix/platform/i386-solaris.rb +11 -11
- data/lib/childprocess/unix/platform/x86_64-linux.rb +12 -12
- data/lib/childprocess/unix/platform/x86_64-macosx.rb +11 -11
- data/lib/childprocess/unix/posix_spawn_process.rb +134 -134
- data/lib/childprocess/unix/process.rb +90 -89
- data/lib/childprocess/version.rb +3 -3
- data/lib/childprocess/windows.rb +38 -33
- data/lib/childprocess/windows/handle.rb +91 -91
- data/lib/childprocess/windows/io.rb +25 -25
- data/lib/childprocess/windows/lib.rb +416 -416
- data/lib/childprocess/windows/process.rb +131 -130
- data/lib/childprocess/windows/process_builder.rb +178 -175
- data/lib/childprocess/windows/structs.rb +148 -148
- data/spec/abstract_io_spec.rb +12 -12
- data/spec/childprocess_spec.rb +447 -422
- data/spec/get_env.ps1 +13 -0
- data/spec/io_spec.rb +228 -228
- data/spec/jruby_spec.rb +24 -24
- data/spec/pid_behavior.rb +12 -12
- data/spec/platform_detection_spec.rb +86 -86
- data/spec/spec_helper.rb +270 -261
- data/spec/unix_spec.rb +57 -57
- data/spec/windows_spec.rb +23 -23
- metadata +8 -39
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: b4e76f415dff2879680f9ca7c48442132fde2099dbdcd956aaf44b429269067b
|
4
|
+
data.tar.gz: b02b05e8ec6ad8a63c31cbaae6067cf5dae11e80b79850ebf9cf630e6fe69ddf
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: ea2985d14f2b941e48dfa544c4531440560e6e4fc7c8edb1bdf68200099f9002cba20e033c0267a5f87bed8f886ae655dd3476c023f1133ce0729d7428610d8f
|
7
|
+
data.tar.gz: d962183e2e67e3612be72a7120a2a083bae78f738662cd8f0af7e50513b9936406814a25136e8a5cb7ae2c3166eb4d3ead38f85be834478b6fd26106c000dd56
|
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
|
data/.travis.yml
CHANGED
@@ -1,44 +1,37 @@
|
|
1
|
-
os:
|
2
|
-
- linux
|
3
|
-
- osx
|
4
|
-
|
5
|
-
rvm:
|
6
|
-
-
|
7
|
-
-
|
8
|
-
-
|
9
|
-
- 2.
|
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
|
-
exclude:
|
39
|
-
# Travis does not provide 1.9.3 on OSX
|
40
|
-
- rvm: 1.9.3
|
41
|
-
os: osx
|
42
|
-
# Travis does not provide 2.0.0 on it latest version of OSX
|
43
|
-
- rvm: 2.0.0
|
44
|
-
os: osx
|
1
|
+
os:
|
2
|
+
- linux
|
3
|
+
- osx
|
4
|
+
|
5
|
+
rvm:
|
6
|
+
- rbx-3
|
7
|
+
- 2.4
|
8
|
+
- 2.5
|
9
|
+
- 2.6
|
10
|
+
- ruby-head
|
11
|
+
|
12
|
+
sudo: false
|
13
|
+
|
14
|
+
cache: bundler
|
15
|
+
|
16
|
+
before_install:
|
17
|
+
- "echo 'gem: --no-document' > ~/.gemrc"
|
18
|
+
- gem install bundler
|
19
|
+
|
20
|
+
before_script:
|
21
|
+
- 'export JAVA_OPTS="${JAVA_OPTS_FOR_SPECS}"'
|
22
|
+
|
23
|
+
env:
|
24
|
+
global:
|
25
|
+
matrix:
|
26
|
+
- CHILDPROCESS_POSIX_SPAWN=true CHILDPROCESS_UNSET=should-be-unset
|
27
|
+
- CHILDPROCESS_POSIX_SPAWN=false CHILDPROCESS_UNSET=should-be-unset
|
28
|
+
|
29
|
+
matrix:
|
30
|
+
allow_failures:
|
31
|
+
- rvm: rbx-3
|
32
|
+
- rvm: ruby-head
|
33
|
+
- env: "CHILDPROCESS_POSIX_SPAWN=true"
|
34
|
+
include:
|
35
|
+
- rvm: jruby-9.2.5.0
|
36
|
+
jdk: openjdk11
|
37
|
+
env: "JAVA_OPTS_FOR_SPECS='--add-opens java.base/java.io=org.jruby.dist --add-opens java.base/sun.nio.ch=org.jruby.dist'"
|
data/CHANGELOG.md
CHANGED
@@ -1,49 +1,77 @@
|
|
1
|
-
### Version 0.
|
2
|
-
|
3
|
-
*
|
4
|
-
|
5
|
-
|
6
|
-
|
7
|
-
|
8
|
-
*
|
9
|
-
|
10
|
-
|
11
|
-
### Version 0.
|
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
|
-
|
1
|
+
### Version 4.0.0 / 2020-06-18
|
2
|
+
|
3
|
+
* [#167](https://github.com/enkessler/childprocess/pull/167): Fix detach behavior on Windows
|
4
|
+
|
5
|
+
### Version 3.0.0 / 2019-09-20
|
6
|
+
|
7
|
+
* [#156](https://github.com/enkessler/childprocess/pull/156): Remove unused `rubyforge_project` from gemspec
|
8
|
+
* [#160](https://github.com/enkessler/childprocess/pull/160): Remove extension to conditionally install `ffi` gem on Windows platforms
|
9
|
+
* [#160](https://github.com/enkessler/childprocess/pull/160): Remove runtime dependency on `rake` gem
|
10
|
+
|
11
|
+
### Version 2.0.0 / 2019-07-11
|
12
|
+
|
13
|
+
* [#148](https://github.com/enkessler/childprocess/pull/148): Drop support for Ruby 2.0, 2.1, and 2.2
|
14
|
+
* [#149](https://github.com/enkessler/childprocess/pull/149): Fix Unix fork reopen to be compatible with Ruby 2.6
|
15
|
+
* [#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
|
16
|
+
|
17
|
+
### Version 1.0.1 / 2019-02-03
|
18
|
+
|
19
|
+
* [#143](https://github.com/enkessler/childprocess/pull/144): Fix installs by adding `rake` gem as runtime dependency
|
20
|
+
* [#147](https://github.com/enkessler/childprocess/pull/147): Relax `rake` gem constraint from `< 12` to `< 13`
|
21
|
+
|
22
|
+
### Version 1.0.0 / 2019-01-28
|
23
|
+
|
24
|
+
* [#134](https://github.com/enkessler/childprocess/pull/134): Add support for non-ASCII characters on Windows
|
25
|
+
* [#132](https://github.com/enkessler/childprocess/pull/132): Install `ffi` gem requirement on Windows only
|
26
|
+
* [#128](https://github.com/enkessler/childprocess/issues/128): Convert environment variable values to strings when `posix_spawn` enabled
|
27
|
+
* [#141](https://github.com/enkessler/childprocess/pull/141): Support JRuby on Java >= 9
|
28
|
+
|
29
|
+
### Version 0.9.0 / 2018-03-10
|
30
|
+
|
31
|
+
* Added support for DragonFly BSD.
|
32
|
+
|
33
|
+
|
34
|
+
### Version 0.8.0 / 2017-09-23
|
35
|
+
|
36
|
+
* Added a method for determining whether or not a process had been started.
|
37
|
+
|
38
|
+
|
39
|
+
### Version 0.7.1 / 2017-06-26
|
40
|
+
|
41
|
+
* Fixed a noisy uninitialized variable warning
|
42
|
+
|
43
|
+
|
44
|
+
### Version 0.7.0 / 2017-05-07
|
45
|
+
|
46
|
+
* Debugging information now uses a Logger, which can be configured.
|
47
|
+
|
48
|
+
|
49
|
+
### Version 0.6.3 / 2017-03-24
|
50
|
+
|
51
|
+
See beta release notes.
|
52
|
+
|
53
|
+
|
54
|
+
### Version 0.6.3.beta.1 / 2017-03-10
|
55
|
+
|
56
|
+
* Bug fix: Fixed child process creation problems on Windows 7 when a child was declared as a leader.
|
57
|
+
|
58
|
+
|
59
|
+
### Version 0.6.2 / 2017-02-25
|
60
|
+
|
61
|
+
* Bug fix: Fixed a potentially broken edge case that could occur on older 32-bit OSX systems.
|
62
|
+
|
63
|
+
|
64
|
+
### Version 0.6.1 / 2017-01-22
|
65
|
+
|
66
|
+
* Bug fix: Fixed a dependency that was accidentally declared as a runtime
|
67
|
+
dependency instead of a development dependency.
|
68
|
+
|
69
|
+
|
70
|
+
### Version 0.6.0 / 2017-01-22
|
71
|
+
|
72
|
+
* Support for Ruby 2.4 added
|
73
|
+
|
74
|
+
|
75
|
+
### Version 0.5.9 / 2016-01-06
|
76
|
+
|
77
|
+
* The Great Before Times...
|
data/Gemfile
CHANGED
@@ -1,15 +1,21 @@
|
|
1
|
-
source
|
2
|
-
|
3
|
-
# Specify your gem's dependencies in child_process.gemspec
|
4
|
-
gemspec
|
5
|
-
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
gem '
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
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,196 +1,230 @@
|
|
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
|
-
|
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
|
-
process
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
process
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
process.
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
74
|
-
|
75
|
-
|
76
|
-
|
77
|
-
|
78
|
-
end
|
79
|
-
|
80
|
-
|
81
|
-
|
82
|
-
|
83
|
-
|
84
|
-
|
85
|
-
|
86
|
-
|
87
|
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
92
|
-
|
93
|
-
|
94
|
-
process.
|
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
|
-
process.
|
148
|
-
```
|
149
|
-
|
150
|
-
|
151
|
-
|
152
|
-
|
153
|
-
|
154
|
-
|
155
|
-
|
156
|
-
```ruby
|
157
|
-
ChildProcess.build(
|
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
|
-
|
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.4+, 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
|
+
begin
|
73
|
+
process = ChildProcess.build("sh" , "-c",
|
74
|
+
"for i in {1..3}; do echo $i; sleep 1; done")
|
75
|
+
process.io.stdout = w
|
76
|
+
process.start # This results in a fork, inheriting the write end of the pipe.
|
77
|
+
|
78
|
+
# Close parent's copy of the write end of the pipe so when the (forked) child
|
79
|
+
# process closes its write end of the pipe the parent receives EOF when
|
80
|
+
# attempting to read from it. If the parent leaves its write end open, it
|
81
|
+
# will not detect EOF.
|
82
|
+
w.close
|
83
|
+
|
84
|
+
thread = Thread.new do
|
85
|
+
begin
|
86
|
+
loop do
|
87
|
+
print r.readpartial(16384)
|
88
|
+
end
|
89
|
+
rescue EOFError
|
90
|
+
# Child has closed the write end of the pipe
|
91
|
+
end
|
92
|
+
end
|
93
|
+
|
94
|
+
process.wait
|
95
|
+
thread.join
|
96
|
+
ensure
|
97
|
+
r.close
|
98
|
+
end
|
99
|
+
```
|
100
|
+
|
101
|
+
Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
|
102
|
+
|
103
|
+
#### Write to stdin
|
104
|
+
|
105
|
+
```ruby
|
106
|
+
process = ChildProcess.build("cat")
|
107
|
+
|
108
|
+
out = Tempfile.new("duplex")
|
109
|
+
out.sync = true
|
110
|
+
|
111
|
+
process.io.stdout = process.io.stderr = out
|
112
|
+
process.duplex = true # sets up pipe so process.io.stdin will be available after .start
|
113
|
+
|
114
|
+
process.start
|
115
|
+
process.io.stdin.puts "hello world"
|
116
|
+
process.io.stdin.close
|
117
|
+
|
118
|
+
process.poll_for_exit(exit_timeout_in_seconds)
|
119
|
+
|
120
|
+
out.rewind
|
121
|
+
out.read #=> "hello world\n"
|
122
|
+
```
|
123
|
+
|
124
|
+
#### Pipe output to another ChildProcess
|
125
|
+
|
126
|
+
```ruby
|
127
|
+
search = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
|
128
|
+
search.duplex = true # sets up pipe so search.io.stdin will be available after .start
|
129
|
+
search.io.stdout = $stdout
|
130
|
+
search.start
|
131
|
+
|
132
|
+
listing = ChildProcess.build("ps", "aux")
|
133
|
+
listing.io.stdout = search.io.stdin
|
134
|
+
listing.start
|
135
|
+
listing.wait
|
136
|
+
|
137
|
+
search.io.stdin.close
|
138
|
+
search.wait
|
139
|
+
```
|
140
|
+
|
141
|
+
#### Prefer posix_spawn on *nix
|
142
|
+
|
143
|
+
If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
|
144
|
+
|
145
|
+
```ruby
|
146
|
+
ChildProcess.posix_spawn = true
|
147
|
+
process = ChildProcess.build(*args)
|
148
|
+
```
|
149
|
+
|
150
|
+
To be able to use this, please make sure that you have the `ffi` gem installed.
|
151
|
+
|
152
|
+
### Ensure entire process tree dies
|
153
|
+
|
154
|
+
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:
|
155
|
+
|
156
|
+
```ruby
|
157
|
+
process = ChildProcess.build(*args)
|
158
|
+
process.leader = true
|
159
|
+
process.start
|
160
|
+
```
|
161
|
+
|
162
|
+
#### Detach from parent
|
163
|
+
|
164
|
+
```ruby
|
165
|
+
process = ChildProcess.build("sleep", "10")
|
166
|
+
process.detach = true
|
167
|
+
process.start
|
168
|
+
```
|
169
|
+
|
170
|
+
#### Invoking a shell
|
171
|
+
|
172
|
+
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.
|
173
|
+
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`.
|
174
|
+
You can work around this by being explicit about what interpreter to invoke:
|
175
|
+
|
176
|
+
```ruby
|
177
|
+
ChildProcess.build("cmd.exe", "/c", "bundle")
|
178
|
+
ChildProcess.build("ruby", "-S", "bundle")
|
179
|
+
```
|
180
|
+
|
181
|
+
#### Log to file
|
182
|
+
|
183
|
+
Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead.
|
184
|
+
|
185
|
+
```ruby
|
186
|
+
logger = Logger.new('logfile.log')
|
187
|
+
logger.level = Logger::DEBUG
|
188
|
+
ChildProcess.logger = logger
|
189
|
+
```
|
190
|
+
|
191
|
+
## Caveats
|
192
|
+
|
193
|
+
* 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`.
|
194
|
+
* 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.
|
195
|
+
|
196
|
+
# Implementation
|
197
|
+
|
198
|
+
How the process is launched and killed depends on the platform:
|
199
|
+
|
200
|
+
* Unix : `fork + exec` (or `posix_spawn` if enabled)
|
201
|
+
* Windows : `CreateProcess()` and friends
|
202
|
+
* JRuby : `java.lang.{Process,ProcessBuilder}`
|
203
|
+
|
204
|
+
# Note on Patches/Pull Requests
|
205
|
+
|
206
|
+
1. Fork it
|
207
|
+
2. Create your feature branch (off of the development branch)
|
208
|
+
`git checkout -b my-new-feature dev`
|
209
|
+
3. Commit your changes
|
210
|
+
`git commit -am 'Add some feature'`
|
211
|
+
4. Push to the branch
|
212
|
+
`git push origin my-new-feature`
|
213
|
+
5. Create new Pull Request
|
214
|
+
|
215
|
+
# Publishing a New Release
|
216
|
+
|
217
|
+
When publishing a new gem release:
|
218
|
+
|
219
|
+
1. Ensure [latest build is green on the `dev` branch](https://travis-ci.org/enkessler/childprocess/branches)
|
220
|
+
2. Ensure [CHANGELOG](CHANGELOG.md) is updated
|
221
|
+
3. Ensure [version is bumped](lib/childprocess/version.rb) following [Semantic Versioning](https://semver.org/)
|
222
|
+
4. Merge the `dev` branch into `master`: `git checkout master && git merge dev`
|
223
|
+
5. Ensure [latest build is green on the `master` branch](https://travis-ci.org/enkessler/childprocess/branches)
|
224
|
+
6. Build gem from the green `master` branch: `git checkout master && gem build childprocess.gemspec`
|
225
|
+
7. Push gem to RubyGems: `gem push childprocess-<VERSION>.gem`
|
226
|
+
8. Tag commit with version, annotated with release notes: `git tag -a <VERSION>`
|
227
|
+
|
228
|
+
# Copyright
|
229
|
+
|
230
|
+
Copyright (c) 2010-2015 Jari Bakken. See [LICENSE](LICENSE) for details.
|