.. index:: single: debugging; remote single: remote debugging **************** Remote Debugging **************** Running a Dylan application on a remote machine =============================================== Open Dylan offers a facility for running, debugging, and interacting with a Dylan application, DLL, or OLE control ("program" hereafter) running on a remote machine—that is, a networked machine other than the one running the Open Dylan IDE. The ability to do these things on the remote machine is a simple extension of the standard features described in :doc:`debug`, which covers debugging and interaction techniques. The techniques for running, debugging, and interacting with a program are exactly the same as for the local machine, but there are a few initial configuration issues to cover. .. index:: single: debugging; server installer Installing the program and debugging server on the remote machine ----------------------------------------------------------------- To do anything with a Dylan program on a remote machine, the program has to be installed there. It may be there already—if, for instance, you are working with another Dylan developer—but if it is not, you must install the program on that machine. To install the debugging server and your program on a remote machine, perform these steps on the target machine: #. Install the Open Dylan runtime system. The runtime installer executable, the name of which begins "*hdrun* ...", resides in the *Extras* folder at the top-level of your Dylan CD-ROM. #. Install the debugging server application. The debugging server installer executable, the name of which begins with "*hddbg* ...", also resides in the *Extras* folder. #. Copy the *bin* folder for your project onto the remote machine. .. index:: single: debugging; debugger server Starting the debugging server ----------------------------- Whenever you try to invoke the program on the remote machine, Open Dylan expects to be able to talk to the debugging server application on the remote machine. If this server is not running on the remote machine, it is not possible to run the Dylan program there either. The debugging server must be started manually on the remote machine itself, so it is worth installing it there. (See `Installing the program and debugging server on the remote machine`_ for information about using the debugging server installer.) Of course, if the remote machine already has the Open Dylan installed on it, you do not need to install the debugging server. To start the debugging server choose **Start > Programs > Open Dylan > Start Debug Server**. You can also invoke it with *debugger-server.exe*, which is available in the *Bin* subfolder of the Open Dylan installation folder. If the debugging server starts up correctly, a Open Dylan Debugger Server window opens. The window provides up-to-date information about active local debugger processes and remote connections. The upper pane of the window shows all locally running processes being debugged on remote machines, and the lower pane shows the remote machines that are connected to the server. A status bar at the bottom of the window displays a summary. You can set (and later change) a password for the debugging server by using the **Change Password** button on the Debugger Server window. The password can be anything. By default, no password is required. To exit the Debugging Server, click the **Exit** button or simply close the window. At this point, you can return to the machine running the Open Dylan IDE, where you will be ready to run Dylan programs remotely. Starting an application remotely -------------------------------- Running and debugging an application on a remote machine is identical in almost every respect to using your local machine. You can use the three menu items **Application > Start**, **Application > Debug** and **Application > Interact** to launch the application in the normal way. The only difference is that for remote startup you must specify a remote machine in the project's debug settings. #. Select **Project > Settings...** and select the Debug page. In the "Remote machine" section, an option box displays the name of the machine on which the project's application is to be run. By default, the selection will be the local machine. Before you can select a remote machine, you must first establish a debugging connection. #. Click the **Open New Connection...** button. #. In the dialog that appears, enter the network address of the machine to which you wish to connect, and enter the password for the debugging server (if one is set), and click **OK**. The address is whatever the Windows operating system needs to identify the machine on the network. A computer hostname is likely to be sufficient. The password is the password established when you first started the debugging server (see `Starting the debugging server`_). If the connection is successful, the newly connected machine is added to those listed in the "Remote machine" option box. You can now select this machine. If the connection does not succeed, you should ensure that you have successfully started the debug server program on the remote machine. (See `Starting the debugging server`_ above.) #. Select the remote machine in the option box. Having selected a remote machine, you must also ensure that Open Dylan can locate the program (EXE or DLL) on the filesystem of the remote machine. #. Specify the path to the program in the "Command line" section of the Debug page. The path should be fully qualified, including the name of the remote machine. For example:: \\spiral\c_drive\apps\reversi\release\reversi.exe where *spiral* is a machine name, and *c\_drive* is the share name of the drive containing the program *release* folder. You are now ready to run and debug the application remotely. **Application > Start** starts your application running on the remote machine. All the usual debugging and interaction facilities will now be available. Details about the connection to a remote machine are stored and saved with the project. Open Dylan tries to re-establish the remote connection automatically when you next open and try to run the project. .. index:: Attach Debugger... menu command on main window Attaching to running processes ============================== The three commands **Application > Start**, **Application > Debug** and **Application > Interact** are all used to launch a program from within Open Dylan. But if the program is running already, perhaps even before you started up the Open Dylan environment, the environment does not know about the process and therefore it has no visible presence in the environment. Open Dylan allows you to "attach" to such a running process, thereby bringing it under Open Dylan's control just as if it had been started by the environment. It is very simple to do this: #. Open the project whose application, DLL, or control is running. #. Choose **Application > Attach...** from the project window, or choose **Tools > Attach Debugger...** from the main window. A dialog listing all available running processes appears. #. Select the process to which you want to attach, and click **OK**. After a few moments, the debugger attaches to the running process, and all the normal debugging and interaction facilities become available, just as with **Application > Start**. .. note:: Open Dylan does not currently offer any facility for detaching from a process. Once it has been attached to the Open Dylan debugger, and all of your debugging work is finished, you will need to close the program down using the **Application > Stop** command. The process to which you attach need not be running on the local machine. You can also attach to a process that is running on a remote machine provided that the debugging server application (see `Starting the debugging server`_) is running on that machine. The process list dialog has an option box that allows you to select the machine whose process list you want to view. There is also an **Open New Connection...** button for creating new connections to remote machines, which works in the same way as described in `Starting an application remotely`_.