Overview

The Curl® IDE deployment tools are designed to enable you to relocate and reconfigure your application to suit various deployment scenarios. Consider the following hypothetical situation:

You develop a Web application that is part of a larger Web site. You do your initial development and testing with the Curl IDE entirely in your local network file system, using local copies of Curl packages, directories of image files, and other resources already present on the site. You then copy your application to a test server for further testing. Finally, you deploy your finished part of the larger application to the Web site. You also want to store design specifications with the application, but do not want to copy them to either the test or the deployment server.

To perform all these tasks effectively, you need tools to help you do the following things:

Build the specific applets, packages, assemblies, and resource directories that your application needs, and manage the relationships between these parts.
Copy your application, including your local copies of site resources, to the test server.
Copy the part of your application that you created to the Web site server, and somehow enable the application to find other resources already located on the Web site server.
Specify that documents containing design specifications should not be copied to the test server or the Web site server.

IDE projects provide deployment tools and a deployment strategy that help you with all of these tasks.

The Curl IDE Deployment Strategy

Summary:

Deployment enables you to:

Define deployment targets.
Deploy your application in different ways to different targets.
Control caching and synchronization
Sign your applet during deployment

The Curl IDE handles project deployment as part of overall project management. The chapter Organizing Your Work with Projects discusses the use of projects during initial application development.

Deployment Targets

To use the Curl deployment system, you must first define one or more deployment targets. A deployment target is a name associated with a location. Because deploying a project involves copying many of the projects resources to the target, the target location must be a directory that the IDE can write files to. If you have direct access to the file system of your Web server, you can deploy your project directly to the server. Otherwise, you must deploy to a directory and transfer the files to the Web server by FTP or some other means.

Each project includes a default deployment target called default that deploys the project to a subdirectory called deploy-default in the project directory. Use the IDE Project Properties dialog to add and modify deployment targets. Select Edit Target Settings on the Project to open the Project Properties dialog with the Targets tab selected. Select Add... to add a new target, and Settings... to modify an existing target. See Targets.

A project can have several deployment targets, but only one target is active at a time. The active target of the current project is listed to the right of the manifest name in the title bar of the IDE project pane. The deployment commands on the Projects menu read Deploy target-name and Deploy target-name for OCC when there is an active deployment target.

The Current Target command on the Projects menu lists all currently available deployment targets for the project, indicates the active target, and allows you to select a new active target.

When you deploy a project, the deployment tool removes all contents from the target directory before writing the new deployed files. For this reason, it is not advisable to write files to this directory other than those the deployment process puts there.

Manifests and Deployment

The purpose of the project manifest is to enable the files in the project to find the resources they need. The IDE automatically updates the project manifest file as you develop your application. The section The Project File and Project Manifest discusses the role of the manifest file in project development.

When you deploy a project, the resources needed by files in the project may be found in a different location. For example, during development you may use a local copy of a package, located in a subdirectory of the project directory. When you deploy the project, the same package may be located in a different directory, where it is shared by several applications. In this situation, the deployed project needs a manifest that is different from the one used during development.

The project Component Target Settings enable you to specify how the IDE should construct a manifest for the deployed project. You also use Component Target Settings to specify other useful deployment information, such as whether to generate documentation for a package.

You can set Component Target Settings individually for each resource in the project. You can also treat a given component differently for different deployment targets. For example, consider the scenario described at the beginning of this chapter. You might need to copy all of the project's resources to the test server. On the other hand, when you deploy to the Web server, you might need to copy some resources, and specify a location on the server where the application can find the rest.

Caching and Synchronization

An important performance feature of the Curl RTE is that it caches packages downloaded by applets that it runs. Performance improves if an applet can use a package already cached on the client rather than downloading it. The end user can control the caching behavior of the RTE on the client through the General tab on the Curl Control Panel. When you deploy a new version of an application to a Web server, you want to be able to ensure that the new versions are downloaded as needed. There are several ways to control synchronization. The section Caching and Synchronization discusses these issues in detail.

Code Signing

Code Signing allows you to digitally sign a Curl applet and its manifest. This feature is available only in the Curl Pro/IDE version. See Curl and Curl Pro Products. Code signing offers the following advantages:

You as the software publisher can guarantee to the application end user that the applet code has not been tampered with since it was signed.
The end user can validate that the application comes from you, the publisher, and that it has not been compromised or subverted.
The end user can decide to allow the signed applet to execute with privilege, execute unprivileged, or not execute.

In order to sign an application, you must first obtain a public key/private key pair from a suitable Certificate Authority. These are institutions such as Verisign® or Thawte® which issue public key/private key pairs. Then you select code signing and specify the certificate file in the Target Settings dialog box. See Targets. The certificate file should be in PKCS#12 format, also known as PFX format.

Signed applets and their manifests contain a {curl-file-signature ...} form near the top of the file. A signed Curl file is not evaluated unless and until the signature is verified. If the signature cannot be verified, the applet or one of its components from the manifest has been corrupted in some manner.

End users running a signed applet interact with a dialog that allows them to select one of the following options:

Run the applet once with privilege; they are prompted again next time.
Not run the applet.
Save the applet certificate and run the applet; they are not prompted again. Applets signed by the saved certificate always run with privilege.
Run the applet without privilege.

If the applet certificate is found to be invalid when running an applet, the end user can select from the following options:

Deny, which results in a syntax error indicating that the certificate has been rejected by user.
Unprivileged, which runs the applet and assigns privilege according to the Privileged Locations set in the Curl Control Panel. An examination of the Process Properties shows that the applet is not signed and its assigned privilege.

Note: Code signing is not supported on Mac platforms.

Deploying for Occasionally Connected Computing

You can also use the IDE deployment system to prepare an archive file for applications that use the Curl Occasionally Connected Computing (OCC) feature. Instead of using the Deploy command on the Project menu, use Deploy for OCC. For more information on OCC, see Occasionally Connected Computing. For more information on the Project menu, see Project Menu.

Editing Component Target Settings

Summary:

Component Target settings let you treat each resource in your project differently on deployment.

Once you have created and selected an active target, you can specify target settings for each file and resource in your project. The target settings determine what the IDE does with that resource when it deploys the project. Use the Show Target Settings command on the Project menu to show setting indicators, which appear to the right of the file name in the Project pane. This menu item for this command changes to Hide Target Settings when the setting indicators are visible.

Select the Edit Component Target Settings command on the Project menu to open the Component Target Settings dialog. You can also open this dialog by clicking on the setting indicator. This dialog lists all setting available for the currently selected resource.

One action that is available for all types of resources is Do not include in target manifest. Use this setting for resources you want to include in your project, but do not want to deploy with the application, such as product specifications or progress notes.

Other settings depend on the type of resource.

Files and Directories

Settings for files and directories:

Copy to target
Copies the file, or the directory and all it contents, to the deployment target directory.
Include in target manifest
Does not copy the file or directory, and uses the same manifest entry in the deployed manifest as in the development manifest.
Include in target manifest using alternate path:
Does not copy the file or directory. The manifest file (manifest.mcurl) written to the deployment target directory specifies the path you enter here as the location for this file or directory.

Packages

Settings for packages:

Copy to target
Copies the package file, often called load.scurl, and all the Curl source files .scurl that make up this package to the deployment target directory.
Generate pcurl in target
Creates a .pcurl file for the package and writes it to the deployment target directory. The .pcurl file has the same name as the package file, and the manifest written to the deployment target directory contains a reference to the .pcurl file. The ability to generate .pcurl files is available only in the Curl Pro/IDE version. See Curl and Curl Pro Products.
Include debugging information
Adds information about the original source files to the pcurl file. Enables you to generate useful stack dumps and step through the code in the debugger. Enabled only when you have selected Generate pcurl in target. Note that selecting this option writes package source code to the resulting .pcurl file.
Include in target manifest
Does not copy files, and uses the same manifest entry in the deployed manifest as in the development manifest.
Include in target manifest using alternate path:
Does not copy files. The manifest file (manifest.mcurl) written to the deployment target directory specifies the path you enter here as the location for this package.
Generate documentation?
Check this option to create API documentation for the package in addition to whatever other settings you have specified. The IDE creates a documentation file .pcdoc that has the same name as the package name. If the package name is DOC.PKG, the documentation file for the package is named DOC.PKG.pcdoc

The documentation file is located in a directory hierarchy within the deployment target directory that is structured like this: target-directory/docs/language/api-ref/.

All package documentation for this deployment target is written to this directory.

See Help Menu for information on how to install documentation so that you can view it with the Curl IDE documentation viewer, and Documenting Your Application for more information on writing documentation for a package.
Apply new setting to all packages?
Check this option to apply the settings you have specified for this package to all packages in the project.

To use deployment most effectively, you need to organize your application so that all Curl source files other than applet files are included in a package file. The IDE determines what files constitute a package by reading the package file and noting include statements. The IDE cannot recognize any files in include statements in .scurl files other than the package file. It also does not recognize files accessed with the evaluate procedure.

Delegate-to

A manifest enables a Curl applet to locate resources. One manifest can use another manifest to provide resource information through the delegate-to mechanism. See Manifest Delegation. You can add a manifest to a project, which adds a delegate-to expression to the project manifest, with the Add Delegate-to command on the Project menu.

Settings for delegate-to:

Include in target manifest
Includes the delegate-to in the project manifest file written to the deployment target directory.
Include in target manifest using alternate path:
Writes a modified version of the project manifest file to the deployment target directory. The manifest in the current, non-deployed location is unchanged.

The modified manifest contains an entry for this resource that specifies as its location the path you enter here.

Deployment Examples

This section uses a several sample projects to illustrate project deployment. You can find this example in c:\build\jcurl\docs\default\examples\uguide\deployment.zip. See Extended Examples for more information on working with extended examples.

Extract the files from this archive into a convenient directory. Extracting the files creates three directories, applet-project, use-package, and use-delegate-to. Each directory contains an IDE project. All of these projects have three deployment targets.

default is the default deployment target provided for all projects. It deploys the project to a subdirectory called deploy-default.
local-deploy deploys the project to c:\Inetpub\wwwroot\, where you can access it as http://localhost. You must have http://localhost set up properly on your local machine to use this deployment target. See Serving Applets from localhost.
directory-deploy deploys the project to a directory on the c:\ drive. This target provides an alternative to deploying to http://localhost. You can change the deployment location to another local directory if necessary.

Deploying Local Resources

First, use the IDE to open the project in applet-project. This project contains an applet file start.curl, a package called DOC.LOGO that contains a source file called show-logo.scurl, and a directory called images that contains a file curllogo.gif. The applet uses the procedure show-logo, which is defined in the package DOC.LOGO, to display the image file located in the directory images.

All of these resources are present in the directory that contains the project. Double click on the root node of the project to open the project manifest file, which contains component expressions that identify the file, package, and directory resources.

Select Show Component Target Settings on the Project menu to see settings for each component. Note that all three deployment targets simply copy the applet and all of its resources to the target.

Deploy APPLET-PROJECT to the default target, and at least one of the additional targets. Note that the applet runs correctly and displays the Curl logo in all deployed locations.

Deploying a Non-local Package

Now use the IDE to open the project in use-package. This project contains an applet file start.curl, and the package DOC.LOGO defined in APPLET-PROJECT. Double click on the root node of the project to open the project manifest file, which contains component expressions that identify the file and package resources. In this case, the location for the package is defined relative to the current project directory.

The component target settings for this project specify that start.curl be copied to the target location. Resources that are not located in the project directory cannot be copied during deployment. Therefore, the package cannot be copied. The component target setting is use path, which instructs the IDE to create a component expression in the deployed manifest that uses the same location path used by the project manifest.

Deploy USE-PACKAGE to the default target, and at least one of the additional targets. Note that the applet does not run correctly in the default target directory, because this directory does not have the same relationship to APPLET-PROJECT. If you copied this directory to a location on a web site where APPLET-PROJECT was already deployed, the applet would run correctly. The alternative deployment targets put the directories in the right relationship to each other, so the applet does run correctly in these locations.

Note that while the applet can use its project manifest to locate the package DOC.LOGO, it has no direct access to the directory images.

Deploying a Delegated Manifest

Now use the IDE to open the project in use-delegate-to. This project contains an applet file start.curl, and a delegated manifest for the project APPLET-PROJECT. Double click on the root node of the project to open the project manifest file, which contains a delegate-to expression that identifies the manifest.

The deployment targets directory-deploy and local-deploy write the project files to the directory DelegateDemo. The project APPLET-PROJECT is deployed to DeployDemo. In order to find the project resources, the component target setting for the APPLET-PROJECT manifest is Include in target manifest using alternate path:. The supplied path specifies the location of the deployed project. This setting instructs the IDE to create a delegate-to expression in the deployed manifest that uses the specified path.

Deploy this project to either of the targets directory-deploy or local-deploy. Like USE-PACKAGE, this project relies on APPLET-PROJECT being present in the correct relationship. Because it uses a delegate-to to add a package manifest, this project has access to all the resources of the project APPLET-PROJECT. The applet start.curl uses manifest-url to access the image file in applet-project directly, as well as through the package DOC.LOGO.

Automated Deployment

You can automate the IDE deployment operation and include it in build scripts and other automated contexts. You can use different deployment targets and perform many different deployment operations on a project, such as creating documentation and pcurling packages.

The Curl IDE includes a script for deploying projects, called deploy-project.xcurl. You can find this script in c:\build\jcurl\ide\bin. See Scripts for more information on writing and using Curl scripts.

Use the following syntax to run the deployment script:

Syntax:

curl deploy-project.xcurl [target] project-file

where flags are:

(--help | --usage | -h | -?)
Print out a help message with the command line options.
(--target | -t) target-name
Deploys the target target-name. If omitted, all targets in the project are deployed.
--occ
Deploys using OCC. If omitted, the deploying is done without OCC support.
(--preflight | -p) (none | dialog | throw)
If dialog or throw, the deploy operation is preflighted before finishing. The preflight checks to make sure that the deploy target directory only contains files that are in the image that is about to be deployed. If dialog, then a dialog is shown to ask the user how to proceed. If throw, then an error is thrown and the deploy fails. If none, then no preflight check is done.
(--verbose | -v)
Print messages to stderr during deployment to describe which targets are being deployed.

If an error occurs while deploying a target, the error is printed to stderr and no more targets are deployed.

The automated deployment API is not documented in the API Reference, so all the required components are described below:

DeployPreflight is an enum with three possible values:

none skip preflight.
dialog display a dialog if the preflight test fails
throw throw an error if the preflight test fails

The class ProjectDescription represents the project state on disk. The factory ProjectDescription.from-url creates a ProjectDescription given a Url to a Curl project (.cprj) file.

The method ProjectDescription.deploy deploys one of the project's targets. It has the following syntax:

Syntax:	{deploy target, occ? = false, preflight = DeployPreflight.dialog }
where:	target is a TargetDescription that determines the target to deploy. occ? is a bool that determines whether deployment is for OCC. See Deploying for Occasionally Connected Computing preflight is a DeployPreflight.

The property ProjectDescription.targets is an Iterator-of TargetDescription that returns all the targets in the project.

The class TargetDescription represents a deploy target in a project. It contains the following fields:

name:String the name of this target.
description:String the description of this target.
target-url-name:String the deploy location for this target, as a path relative to the project's manifest directory.
password:#String the signing password for this this target's certificate. This is only used if code signing is enabled for this target.

Copyright © 1998-2007 Sumisho Computer Systems Corp. All rights reserved.
Curl, the Curl logo, Surge, and the Surge logo are trademarks of Sumisho Computer Systems Corp. that are registered in the United States. Surge Lab, the Surge Lab logo, and the Surge Lab Visual Layout Editor (VLE) logo are trademarks of Sumisho Computer Systems Corp.