Installing and Running the Platform Assistant (paserver) on the Target Platform

From RAD Studio XE2
Jump to: navigation, search

Go Up to Steps in Creating Cross-Platform Applications

Go Up to Command Line Utilities Index


In order to use the IDE to develop cross-platform applications, you need to install and run the Platform Assistant on the target platform. The Platform Assistant file name is paserver, the remote application server. If you use the default port number (64211), you should be able to use the Platform Assistant without changing any parameters. To change parameters, see either Setting Options for paserver or paserver.config File.

When you install the Platform Assistant on the target platform, the necessary cross-platform library elements are installed in the PAServer installation directory. The Platform Assistant installs files such as those that are necessary for debugging a cross-platform application.

You Must Connect to the Platform Assistant at Specific Times

Important: To run, debug, and deploy a cross-platform application, RAD Studio must be connected to the Platform Assistant that is running on the target platform.

You must ensure this connection whenever you:

  • Test the connection of a remote profile.
  • Run your cross-platform application.
  • Debug your cross-platform application.
  • Deploy your cross-platform application.

At other times during application development, you do not need to have the target platform connected and running the Platform Assistant.

Mac: Installing and Running the Platform Assistant (paserver) on a Mac

The installer for the Mac is setup_paserver.zip, located in the PAServer folder inside your product installation directory, by default:

C:\Program Files\Embarcadero\RAD Studio\n.n\PAServer\setup_paserver.zip

The name of the executable is paserver.

To Install the Platform Assistant Server on a Mac

  1. On the Mac, download setup_paserver.zip from the location given above to a local directory.
  2. Unzip the file by double-clicking the zip file in the Finder.
    Or unzip the file from the command line using the following command in a Terminal window:
    unzip setup_paserver.zip
  3. Double-click the setup_paserver installer in the Finder. The InstallAnywhere Platform Assistant Server installer launches.
  4. Select your target language (such as English) and click OK.
  5. By default, the Platform Assistant is installed in the Applications/Embarcadero/PAServer directory. On the "Please choose a destination folder" page, you can change the installation location or accept the default. The Platform Assistant should start successfully when using the default port, 64211.

To Run the Platform Assistant on a Mac

The default install location is under your Applications folder on the Mac (/USER_HOME/Applications/Embarcadero/PAServer).

  1. Open a terminal window.
  2. Use the cd command to change to the Platform Assistant directory (Applications/Embarcadero/PAServer):
mymac:~ myname$ cd Applications
mymac:Applications myname$ cd Embarcadero
mymac:Embarcadero myname$ cd PAServer
mymac:PAServer myname$
3. Launch the Platform Assistant using the following command:
mymac:PAServer myname$ ./paserver

Note: A "command not found" message is displayed if you do not start the command with the required ./ ("dot-slash").

The paserver banner and password prompt appears:
Platform Assistant version 1.0.2
Copyright (c) 2009-2011 Embarcadero Technologies, Inc.
Remote Profile password <press Enter for no password>:
4. At the Remote Profile password: prompt, choose one of the following:
  • To set a password that will be required to be in any remote profile that connects to this paserver process, enter a password of your choice, and press Enter.
In this case, the password must be correctly specified in the remote profile being used by the cross-platform application.
  • To not require a password for connecting to this paserver process, press Enter.
In this case, no password is required in the remote profile.
5. Acquiring Permission to Support Debugging on the Mac
On the OS X platform, the Platform Assistant uses Developer Tools Access to ensure that you can debug your OS X application. The first time you start the Platform Assistant during any session on the Mac, the following prompt appears (after the password prompt):
Acquiring permission to support debugging...
Now the Mac displays the Developer Tools Access dialog box:
 Type your password to allow Developer Tools 
 Access to make changes.
The password for Developer Tools Access is required only once per user session in order to grant permission for debugging. Enter the administrator password for the Mac (typically the password you enter when you log on to the system):
  • If you enter the correct password, the message succeeded is displayed on the Mac.
In this case, you can now run, debug, and deploy your OS X application on the Mac.
  • If you do not enter the correct password (or if you press Cancel), the message failed is displayed on the Mac, followed by:
    You will be prompted for Developer Tools Access the next time you start the debugger.
In this case:
  • You can run and deploy your OS X applications for the rest of your session on the Mac (but you cannot yet debug).
  • When you attempt to run with debugging (such as Run or F9), the Developer Tools Access dialog box appears. You need to log on to Developer Tools Access in order to debug your OS X application using the IDE.

Note: Using the -nopermissioncheck option: To delay the Developer Tools Access step, start the Platform Assistant with the -nopermissioncheck option:

./paserver -nopermissioncheck

This option delays the need to enter the password for Developer Tools Access until you actually debug an application.

For more information, see Debugging Cross-Platform Applications#On Mac OS X Platform, Debugger Needs File Permissions.
Finally paserver displays the port number it is using:
Starting Platform Assistant Server on port 64211 
>
The > command prompt indicates that the Platform Assistant is in "listening" mode and is ready to communicate with its client on the development PC for running, debugging (if enabled by Developer Tools Access), or deploying a Mac OS X cross-platform application.
6. When you are finished with your development session, close the Platform Assistant process by typing q (quit) and pressing Enter at the Platform Assistant command prompt:
> q

Win64: Installing and Running the Platform Assistant on a Win64 Target

The installer for Win64 is setup_paserver.exe, located in the PAServer folder inside your product installation directory, by default:

C:\Program Files\Embarcadero\RAD Studio\n.n\PAServer\setup_paserver.exe
  1. Copy setup_paserver.exe to the directory of your choice on the Win64 system.
  2. Run setup_paserver.exe, which installs the Platform Assistant.
    During installation, select or create an installation directory that is not located in C:\Program Files. The recommended directory is: C:\Users\name\AppData\Roaming\Embarcadero\PAServer.
  3. To run the Platform Assistant on a Win64 system, do either of the following:
    • Double-click paserver.exe in Windows Explorer.
    • Open a cmd window, cd to the installation directory of PAServer, enter paserver, and press Enter.
    paserver displays its banner and password prompt:
Platform Assistant version 1.0.2
Copyright (c) 2009-2011 Embarcadero Technologies, Inc.
Remote Profile password <press Enter for no password>:

  1. At the Remote Profile password: prompt, choose one of the following:
    • To set a password that will be required to be in any remote profile that connects to this paserver process, enter a password of your choice, and press Enter. In this case, the password must be correctly specified in the remote profile being used by the cross-platform application.
    • To not require a password for connecting to this paserver process, press Enter. In this case, no password is required in the remote profile.

Now paserver displays its command prompt (>).

Uninstalling the Platform Assistant

If you need to install a new version of the Platform Assistant, you should first uninstall the existing Platform Assistant application:

  • On Windows, use Uninstall PAServer.exe to uninstall the Platform Assistant.
  • On the Mac, use the Uninstall command to uninstall the Platform Assistant.

The Uninstall programs are located in the installation directory for the Platform Assistant on the PC and on the Mac.

paserver Help

There are two ways to get online help from paserver.

Running paserver and Including the Help Option

To display "verbose" help, start paserver from the command line and include the -help option, as follows:

C:\>paserver -help
Platform Assistant Server  Version 1.0.2
Copyright (c) 2009-2011 Embarcadero Technologies, Inc.
Usage: paserver [options>]

where <options> include:
 -port=<nnnnn>        Specify the port number, default=64211
 -scratchdir=<dir>    Specify the parent directory for client temporary files
 -libextension=<cmd>  Specify the dynamic library extensions, default=,dylib, h
 -tarcommand=<cmd>    Specify the path for tar binary, default=/usr/bin/tar
 -debuglauncher=<app> Specify the debugger launcher application
 -nopermissioncheck   Do not attempt to acquire permission to support debugging
 -unrestricted        Allow put and remove file(s) operation outside client
                      temporary files directory, default is not allowed
 -password=<text>     Specify the remote profile login password, default is
                      to prompt for the login password
 -passfile=<file>     Specify the remote profile login passfile, default is 
                      to prompt for the login password
 -config=<file>       Specify the default settings
 -help                Print this help screen

Displaying Help When paserver is Running

After paserver is running on the target platform, you can enter h at the command prompt to display help for the five commands to which a paserver process can respond (to do anything other than these, you need to quit and restart). For example:

> h
q - stop the server
c - print all clients
p - print port number
s - print scratch directory
g - generate login passfile
>

Notes:

  • The scratch directory is used by the Platform Assistant for temporary file operations, including remote profiles and project files.
  • The .passfile is a password file that contains an encrypted password for the Platform Assistant; you can share this file with anyone who needs to use the connection, without compromising the privacy of the password.

Setting Options for paserver

The default values for port, password, and scratch directory are:

  • Port number 64211
  • No password required
  • Scratch directory located inside the PAServer installation directory
    • The scratch-dir folder contains your remote profile and project folders, and related files.

You can set the port, password, and scratch-dir parameters either in your command to run paserver or in the paserver.config File. You can specify a different config file for paserver by using the -config option. You can also create an encrypted password file (.passfile) so that another person can connect to paserver without knowing the password you have set for it.

The value for an option is determined as follows:

  1. Command option: The option value specified in your command to run paserver has precedence.
  2. Config file: The option value specified in the paserver.config file is used if no option value is specified in the paserver command.
  3. Default value: If neither of the first two exists, the built-in default value for the option is used.

Setting the Port Number

Include the -port option in your command to start paserver. For example, to specify a port other than the default 64211:

Windows:

> paserver -port=nnnnn

Mac:

> ./paserver -port=nnnnn

The port number must be between 1 and 65,535.

Setting the Password

When you start the Platform Assistant, you can optionally specify a password that will be required to be in any remote profile that attempts to connect to this paserver process.

The Platform Assistant displays the following password prompt:

Remote Profile password <press Enter for no password>: 

Here are your choices:

  • Specify a password if you want the paserver process to require that particular password from each remote profile before allowing the connection.
  • Press Enter at the prompt if you do not want a password to be required from each remote profile.
  • You can alternatively set the paserver password by adding the -password option to your command to start the Platform Assistant, as follows:
 paserver -password=B2C3d4!

Generating and Using a .passfile

You can create one encrypted password file (.passfile), located in the PAServer installation directory. If you start paserver with the .passfile option, paserver requires a remote profile to contain the password that is encrypted in the .passfile. You can share the encrypted password file with other users so that they can connect to your paserver using a remote profile that shares the .passfile.

Generating a .passfile

While paserver is running, you can generate a .passfile that encrypts the password you specified when you started paserver:

  1. Start paserver:
    • Windows: C:\dir\PAServer > paserver
    • Mac: PAServer username$ ./ paserver
  2. At the password: prompt, enter a password of your choice and press Enter.
  3. At the paserver prompt, enter the g option (generate loging passfile):
    > g
    paserver displays a confirmation message, such as:
    directory\PAServer\paserver.passfile generated

In order to connect to this paserver process, a remote profile must contain the name of this .passfile in the Password field.

Starting paserver with a .passfile

Start paserver and include the passfile option, as follows:

Windows: > paserver -passfile=filename

Mac: paserver username$ ./ paserver -passfile=filename


In order to connect to this paserver, a remote profile must contain the name of this .passfile in the Password field.

Specifying a .passfile in a Remote Profile

In order to connect to a paserver that was started with a -passfile option, a remote profile must contain the name of the .passfile in the Password field.

  1. Go to Tools > Options > Environment Options > Remote Profiles.
  2. On the Remote Profiles dialog box, select the remote profile that you want to use the .passfile.
  3. Click the ellipsis [...] in the Password field.
  4. Navigate to the .passfile on the target platform. The directory containing the .passfile must be shared on the network.

Managing the Scratch Directory

The Platform Assistant has a configurable scratch directory that is used for executable file output during application development.

The scratch-dir directory is located by default inside the directory where you installed the Platform Assistant (paserver.exe) on the target platform. Inside the scratch directory, the Platform Assistant saves project output files in profile-specific folders whose names include your user name and the remote profile in use:

PAServer\scratch-dir\username-profilename

For example, on OS X, your compiled executable files (such as ProjectName) are saved in a directory such as:

   Applications \ Embarcadero \ PAServer \ scratch-dir \ MyUserName-MyOSXRemoteProfile

The scratch directory also contains any additional files that are required in order to run your application. For example, the scratch directory on OS X includes dylib files, a Contents folder containing the Info.plist file and possibly a Resources folder for resource files such as .icns (icon) files.

Specifying an Alternate Scratch Directory

To explicitly set the scratch directory location, do either of the following:

  • Use the -scratchdir option in your command to start paserver.
  • Edit the paserver.config file on the target platform; for details, see #paserver.config File.

The -scratchdir option controls only the projects that you run with the paserver process you start using the -scratchdir option; it does not change the scratch directory permanently.

For example, to start the Platform Assistant and specify a directory named TestDir as the scratch directory, here are the command lines to use (on specific target platforms):

On Windows: > paserver -scratchdir=TestDir

On Mac: paserver username$ ./ paserver -scratchdir=TestDir

The paserver that is started with this command saves executables in a directory named TestDir, located in the PAServer installation directory, alongside the existing scratch-dir directory.

On Mac OS X, you can specify an alternate scratch directory in relation to your user directory by prefacing the directory name with a tilde-slash (~/) when you start paserver:

> ./paserver -scratchdir=~/MyTestDir

This command saves executables on the Mac in the /Users/myusername/MyTestDir directory.

Allowing File Operations Outside the Scratch Directory

Caution: Using -unrestricted mode with paserver is not recommended.

By default, paserver operates in restricted mode. That is, the Platform Assistant performs file operations (put and remove) only inside the scratch directory for your remote profile (located inside the PAServer installation directory). In the default (restricted) mode, paclient.exe and the Deployment Manager can add or delete files only inside the paserver scratch directory.

However, if you specify -unrestricted in your command to start paserver, the Platform Assistant allows file operations outside the paserver scratch directory.

paserver.config File

The Platform Assistant has a configuration file installed in the same directory. The paserver.config file can contain any of the parameters accepted by paserver (see Running paserver and Including the Help Option).

By default, the paserver.config file contains only the following two commands, but you can edit these commands and add other paserver commands (such as passfile, password, and unrestricted):

port=64211
scratchdir=

These two commands set the following:

  • The communication port (the default value is 64211)
  • The scratch directory (used for paserver file operations)
The default scratch directory is named scratch-dir and is located inside the directory where paserver.exe is installed. A separate folder is created for each remote profile. For example, the default scratch directory for the MyOSX remote profile is: username-MyOSX.

Note: Using the default values is highly recommended. However, if you want to assign different values for the port and scratch directory, you can do so in two different ways:

  • Edit the paserver.config file:
    • Replace the port number (64211 is the default) with the port number you want to use.
    • Add the scratch directory name without quotation marks. For example:
    scratchdir=Test_dir_3
  • Specify command-line options when you start paserver. For an example, see #Specifying an Alternate Scratch Directory.

Connection Issues

  • To test the connection between your development system and the target platform, use the Test Connection button on the Remote Profiles page in Tools Options.
  • If you receive a "Connection refused" error message related to Platform Assistant Server version mismatch, update your paserver installation on the target platform to the version number specified in the error message. When you run PAServer on the target platform, its version number is displayed in its banner.
  • For information about the "Acquiring permission to support debugging" message or about problems when trying to debug a Mac OS X application, see "Debugger Needs File Permissions on Mac OS X Platform" in Debugging Cross-Platform Applications.
  • For information about a message from Windows Firewall when trying to connect to a Win64 system, see Connecting Your PC to a Win64 PC.

See Also