OSSubprocess is a project that allows the user to spawn Windows System processes from within Pharo language. The main usage of forking external OS processes is to execute OS commands (.e.g dir, copy, etc) as well as arbitrary commands (.e.g C:\Users\me\myscript.bat or pharo.exe) from Pharo. This library uses the Windows API to create process from both 32-bit and 64-bit Pharo images. It also supports Unicode characters.
OSWinSubprocess name is really closed to the name of the OSSubprocess projet that allows to spawn external Unix or OS X processes. OSWinSubprocess and OSSubprocess are complementary and share a part of the API. A mid-term goal would be to unify these projects under the same umbrella.
Important note: As of now, this library does not yet support standard streams (stdin, stdout and stderr). It could be done by setting the appropriate information in the STARTUPINFO structutre.
Currently, OSWinSubprocess has only be tested on Pharo 7.0. From within Pharo, execute the following to install OSWinSubprocess:
Metacello new baseline: 'OSWinSubprocess'; repository: 'github://pharo-contributions/OSWinSubprocess:master/repository'; load.
OSWinSubprocess is quite easy to use but depending on the user needs, there are different parts of the API that could be used. We start with a basic example and later we show more complicated scenarios.
OSWSWinProcess new shellCommand: 'echo' arguments: #('ok'); runAndWait.
A subprocess consist of at least a command/binary/program to be executed (in this example
echo) plus some optional array of arguments.
Running a process is as simple as:
OSWSWinProcess new command: 'C:\Windows\notepad.exe'; runAndWait.
Notice that this call is blocking. You Pharo image is not responding until you close Notepad.exe. To overcome this issue, you can just run the process and keep a reference to it to konw if it is still running or just terminate it.
process := OSWSWinProcess new command: 'C:\Windows\notepad.exe'; run. ... process terminate.
You can call a program and give it arguments.
OSWSWinProcess new command: 'C:\Windows\notepad.exe'; arguments: #('notepad.exe' 'foo.txt'); runAndWait.
Notepad will ask you to create a new file because it cannot find a file foo.txt. Note that we give the program as a first argument because it is expected by notepad.
Now, create a small file
C:\ (with the UI or with a command line with administrator privileges:
echo foo > C:\foo.txt).
You can now open the file with Notepad:
OSWSWinProcess new command: 'C:\Windows\notepad.exe'; arguments: #('notepad.exe' 'C:\foo.txt'); runAndWait.
Another way to achieve the same operation would be to set the working directory for the command being called:
You can also configure the directory that will be used as working directory:
OSWSWinProcess new command: 'C:\Windows\notepad.exe'; workingDirectory: 'C:\'; arguments: #('notepad.exe' 'foo.txt'); runAndWait.
OsWinSubprocess offers some facilities to run a command line within a shell:
shellCommand:runs a Windows cmd.exe shell with the provided command, i.e. a string with the command name and arguments.
shellCommand:arguments:runs a Windows cmd.exe shell with the provided command and a collection of arguments. Warning: Paths with spaces need to be surrounded by double quotes.
OSWSWinProcess instances gives you an high-level API to run and possibly wait for the process termination. It also allows you to get back some information on the process.
runAndWaitRuns the process AND waits until the child has exited. Warning: this method freezes the image until the forked process exits.
runAndWaitTimeOut: nbMilliSecondsRuns the process AND waits until the child has exited.
runUnwatchUsed to run a process and forget about it
runRuns the process and watch it
terminateTerminates (kill) the process. Will set a non-success exit code (3).
isRunningAnswers true if the process is still running, else false.
isCompleteAnswers true if the process is not running and exitCode is set, else false.
isSuccessAnswers true if the process is not running and exitCode is 0 and no error happened, else false.
hasTimedOutAnswers true if the process did not terminate before the given timeout, else false.
exitCodeReturns the process exit code if set, else nil
lastErrorGives you the last error code value. See Windows API documentation for more information
- no management of standard streams (stdin, stdout and stderr)
- one process watcher per process instance (could have only one process watcher for all processes)
- Keldon Alleyne - Initial binding to the Windows API through FFI - Keldon Alleyne
- Christophe Demarey - Initial work - Christophe Demarey
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE file for details