Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View cross-platform shell on the plugin site for more information.

This plugin defines a new build type to execute a shell command in a cross-platform environment.

Description

Cross platform shell executor.

Using Jenkins built-in "Execute Windows batch command" you can run commands using the windows shell.

Using Jenkins built-in "Execute shell" you can run commands using unix shell.

If you need to run a job cross platform you cannot use the two standard executors provided by Jenkins. You need a "build step" that can be executed both in Windows and in Unix.

This plugin does exactly this: it takes a command, as the two standard build steps do, and executes it calling the correct shell depending on the operating system running on the current job executor.

What it does...

  • It runs any executable (with complete command line) available in the system from current working dir (command must be in Path or in job's workspace directory or subdirectory).
  • Automatic conversion of file separator is done according to the executing operating system.
  • Variable style is converted according to the executing operating system. E.g. $JOBPARAM1 is converted to %JOBPARAM1% in the command if the executing operating system is Windows.

Constraints:

  • the current working directory of the command execution is always the job's workspace root.
  • ./ must not be included in command line (use the configuration switch provided to specify that command is in current working dir or subdir).

Examples:

Example 1: run executable + script with parameter

Write your command in the *nix style:

php scripts/build.php $JOBPARAM1

If the command runs on a *nix node, the command runs un-altered. If it runs on a Windows node, it is changed to:

php scripts\build.php %JOBPARAM1%

Note that the file separator and variable naming convention have changed.

... and what it does not!

Command translation problem

Description

It cannot translate any command! So you cannot write

rm -rf bin

because on windows rm command is not available.

Solution

You can wrap your commands in two scripts, one for windows and one for unix, each one calling the right command for the operating system:

clean
rm -rf bin
clean.bat
del /F /S bin

and then call clean using an XShell build step.
This will execute clean in unix and clean.bat in windows.

Notes

  • in windows you can call clean and get clean.bat called, in unix you can't (so the solutions above work);
  • in unix you have to specify if the command is in the current working dir (and if it is not available it will not be searched in PATH), in windows you haven't to.

Build step configuration

To add a XShell build step

  • click on the Add build step button and choose Invoke XShell script;
  • fill in the command line text;
  • choose if the executable is in global Path or in workspace.

TODO

  • Allow execution from a custom working dir (different from workspace dir)
  • Run executable from workspace directory (in unix must be written using ./ form). DONE in 0.2
  • Replace any '\' or '/' in the command line with File.separator
  • Set environment variables... (see comments)

Version history

Version 0.10 (Dev)

Version 0.9 (Nov 10, 2013)

Version 0.8 (Apr 11, 2012)

Version 0.7 (Dec 29, 2011)

  • Added environment variable format conversion (e.g. $VAR to %VAR% for Windows launcher) - Thanks to tclift (https://github.com/tclift)

Version 0.6 (Mar 1, 2011)

  • Updates for Jenkins

Version 0.4 (Sep 22, 2010)

  • Modified regex for path separator replacement that was causing an exception JENKINS-7538
  • Added build variables to environment variables (as in CommandInterpreter).

Version 0.3 (May 18, 2010)

  • Replace any '\' or '/' in the command line with correct file separator (selected using OS where the task is executed).

Version 0.2 (Mar 26, 2010)

  • Run executable from workspace directory also in unix.

Version 0.1 (Mar 25, 2010)

  • Initial release
  • Runs a single command line

14 Comments

  1. Unknown User (axel.heider@gi-de.com)

    Could you add these things:

    • "run from sub-directory", where slashes are converted automatically
      I have a workspace where the following scripts should run: foo/bar/doItAll, foo/bar/doItAll.bat.
      If I give "foo/bar/doItAll", the linux build works, but windows gives this:
         [trunk] $ cmd.exe /C '"foo/bar/doItAll && exit %%ERRORLEVEL%%"'
         command not found
         Finished: FAILURE
    • set environment varienbles for all axises in matrix builds, like in "Execute Windows batch command" and "Execute shell"
      Exmaple: AXIS1=[alpha,beta], AXIX2=[foo,bar]. in the scripts, the variables AXIS1 and AXIX2 should be set.
    1. Unknown User (mambu)

      Hi,

      I have changed the plugin to replace '\' and '/' with File.separator.

      I guess this should be enough to solve your first problem... about the second... maybe it will take some more time.

      1. Unknown User (axel.heider@gi-de.com)

        Thanks. Does ist also convert the slashes the other way, ie "/" to "\"?

        1. Unknown User (mambu)

          Yes, it works in both ways.

          I have released 0.3 with this modification included. I have tried it in my test installation, can you try it and report any problem or other suggestion? Thanks.

    2. Unknown User (mambu)

      I have added the build variables to the environment variables; if the variables added in a matrix project are 'build variables' maybe we have solved the issue you reported (2nd item in your comment).

  2. Unknown User (ssbarnea)

    I suspect that this plugin is borken, see http://issues.jenkins-ci.org/browse/JENKINS-7538

    I tried to assign the bug to the `xshell` component but there is no component with this name.

  3. Unknown User (lephasme)

    Version 0.7 introduced the conversion of environment variable format ($VAR to %VAR%), but this conversion seems to be done in a wrong way and it breaks some jobs, e.g.: the string $VAR/path is converted into %VAR/path% instead of %VAR%/path (which should be more logical).

    And same comment as above: I tried to assign a bug to the shell component, but in vain.

  4. Unknown User (clalarco)

    I found a bug: when source code management (SCM) is used with subversion before a xshell script, in Windows xshell places its working dir in the folder used by SCM, not workspace dir.

    For example, if I retrieve a folder called MyRepo, Xshell starts in workspace/MyTest/MyRepo, so no files are found.

    Some workaround can be used, but "windows shell command" works fine.

    Output console (in both 'windows shell' and 'xshell' scripts 'dir' command was called, first one is 'windows shell'):Started by user clalarco
    Building remotely on multi-os-jnlp in workspace /jenkins/workspace/multi-os-test2
    Reverting \jenkins\workspace\multi-os-test2\MainRegression
    Updating http://localhost/MyRepoAt revision 2052
    no change for http://localhost/MyRepo since the previous build
    multi-os-test2 $ cmd /c call C:\Users\nimbican\AppData\Local\Temp\hudson492387263840934438.bat

    C:\jenkins\workspace\multi-os-test2>dir
    Volume in drive C is windows7_i386
    Volume Serial Number is 80F5-264B

    Directory of C:\jenkins\workspace\multi-os-test2

    09/20/2012 06:47 PM <DIR> .
    09/20/2012 06:47 PM <DIR> ..
    09/20/2012 07:08 PM <DIR> MyRepo
    1 File(s) 28 bytes
    4 Dir(s) 9,303,769,088 bytes free

    C:\jenkins\workspace\multi-os-test2>exit 0
    MyRepo $ cmd.exe /C '"dir && exit %%ERRORLEVEL%%"'
    Volume in drive C is windows7_i386
    Volume Serial Number is 80F5-264B

    Directory of C:\jenkins\workspace\multi-os-test2\MyRepo

    09/20/2012 07:08 PM <DIR> .
    09/20/2012 07:08 PM <DIR> ..
    09/20/2012 06:32 PM 18,745 installbinaries.py
    09/20/2012 06:32 PM 19,735 installbinariesJenkins.py
    2 File(s) 38,480 bytes
    0 Dir(s) 9,303,769,088 bytes free
    Finished: SUCCESS

    1. Unknown User (clalarco)

      I found that commands are executed from the first retrieved repo's folder, so if you perform a retrieval to '.' xshell runs from the workspace directory.

      1. Unknown User (vsnijders)

        I have tried to fix that in pull request 6 which has been merged.

  5. Unknown User (achoo)

    I've tried updating PATH to include a directory that has some of my scripts. But when I try to call them from XShell, they can't be found. The slave is Mac OS X. I added a build step before the one in question and it prints out PATH which includes my scripts directory as expected. Does this work on a Mac slave and if so, how can I troubleshoot the issue?

    1. Unknown User (achoo)

      Never mind. Ended up using something like ../../a/path/relative/to/the/workspace/script

  6. Unknown User (jskull)

    Firstly, thank you very much for writing this plugin.

    Please could you update the "and what it does not" description regarding variable exspansion - I've spent time writing a shell script and batch file to perform variable substitutions, only to find that it is already supported automatically.

  7. Unknown User (dardyjak)

    Hi,

    When do you plan to release new version ? I'm interested in JENKINS-25600 fix :-)

    Regards,

    Darek