Define synchronization directories

Synchronization directories allow you to compile, run, and debug files that sit on a remote server.

Before you begin

This task assumes you have added a remote host. You must connect to the remote directory using SSH.

Warning:

Do not delete the server directory during an operation on the files.

About synchronization directories

When you define a synchronization directory, you provide a local directory path (on the client machine) and a remote directory path (on the remote host). At the time of setup, the remote directory path must be empty. The initial synchronization will copy the files from the local directory to the remote directory.

Once the synchronization directory is defined, all file modifications must happen in the local directory, and all new files must be added to the local directory. Never edit files directly in the remote directory, as the changes will be lost at the next synchronization; files added directly to the remote directory will be removed at the next synchronization.

Synchronization is a two-step process: the first step synchronizes the files from the client to the server, and the second set synchronizes the files from the server back to the client. The second step - from the server back to the client - is used to bring back the results of an operation, such as a build. For example, compiling a .4gl file results in a .42m file; it is the .42m file that is returned and written to the client.

Synchronization directories do not allow users to share the same set of files in a remote directory, as this solution does not support any form of conflict management or source file merging.

Steps for creating a synchronization directory
  1. Select Tools > Server Connections.
    The Server connections window opens.
  2. Select the remote host from the list.
  3. Select the Use synchronization radio button.
  4. Click the Add synchronization directory icon. The icon is a plus sign.
    The New synchronization directory window opens.
    1. Specify the local directory path.
      The local directory path is where your source files will be stored on the local machine. The path must be an absolute path.
    2. Specify the remote directory path.
      The remote directory will be synchronized with the local directory. To start, this directory must be an empty directory.
      Once a remote directory is associated with the local directory, it is not possible to associate it with another local directory.
    3. Specify files or directories to exclude from synchronization (optional).
      Enter a list of names or patterns, separated by spaces. For example, *.42m .txt
      Important:

      If you wish to exclude a directory whose name starts with a period, you must include the backslash at the end of the directory name; otherwise, the tool attempts to exclude an extension file of the same name. For example:

      • An entry of ".svn/" excludes the directory .svn.
      • An entry of ".svn" excludes an extension file named .svn.
    4. Specify whether to ignore the checksum.

      An MD5 checksum is a 32-character hexadecimal number that is computed on a file. If two files have the same MD5 checksum value, then there is a high probability that the two files are the same. As part of the synchronization process, the MD5 checksum value is used to validate the success of the transfer. When the MD5 checksum values do not match, an error displays and the failed copy is removed.

      There are instances where the error in the MD5 checksum is expected based on the remote configuration setup. In these cases, you can choose to ignore the checksum by selecting the Ignore checksum checkbox.
    5. Click Validate Path.
      A message displays if the path is a valid synchronization directory.
    6. Click OK.
  5. (Optional) When using synchronized drives and connecting to a Genero Studio server using public / private keys, select the Use ssh-agent checkbox.
  6. Click Apply, then click OK.
  7. Define remote Genero installations, GAS configurations, and environment sets.
When you execute a project manager operation (such as build, run, or debug), Genero Studio:
  • Checks whether the files belong to a synchronization directory.
  • If the files are part of a synchronization directory, it synchronizes the local directory with the remote directory before executing the operation. When the synchronization is complete, the remote directory is identical to the local directory.
  • After the gsmake operation completes on the server (such as a build, compile, or run), a second synchronization is performed from the remote directory to the local directory. When complete, the local directory is identical to the remote directory, with the exception of files specified in the Excluded extensions field.

If Genero Studio does not find a directory with these files, an error is thrown and the operation stops.

Note:

Directories have a lock mechanism to prevent two instance of Studio from synchronizing with the remote directory simultaneously. Occasionally, the directory can be stuck in a locked state and no operations can be performed. In this case, select Tools > Genero Tools > Unlock Synchronization Directory.