UsersGuide:Chapter 15:Choosing a Target Platform
From Real Software Documentation
Contents |
Choosing a Target Platform
Before you build your Desktop application, you choose the platform or platforms on which it will run. Real Studio can build for Windows, Linux, and Mac OS X. You can build for any or all of these platforms simultaneously. In the language, you can selectively enable or disable segments of your code that are valid only for particular platforms. You use a group of compilation constants to do so. These constants are automatically are set to either True or False depending on which platform you are compiling for. The options that you select in this dialog box determine which constants are True for that build. In your code, you can use an If..Then structure that uses the desired compilation constant to enable or disable code segments.
Beginning with version 2010 Release 3, Real Studio includes an option for compiling to a Macintosh Cocoa target. As of 2010 Release 3, Cocoa support is available as a beta to encourage widespread testing.
At this stage of the process, you can either build an application for one or more desktop platforms or for deployment on the web. You can choose an appropriate target, depending on that choice. You cannot build a desktop application for the web or vice-versa.
To choose a Desktop Application target platform, do this:
- Choose Project ↠ Build Settings.
The Build Settings dialog box appears.
If you are building a Web application, you first need to specify a target on which the Web application will run. If you display the Build Settings dialog from a Web app, the dialog shown below is displayed. Use the General tab of the Build Settings dialog to choose the platform on which the server will run. Use the Web panel to choose the type of Web app.
Then use the Web tab to choose your web settings. Your choices are:
Target Platforms for the Desktop
By default, the operating system that you are currently running is selected. You can choose as many other targets as you wish.
Note that the Personal version of Real Studio builds only demo versions of the application for platforms other than the one on which the IDE is running. Only the Web or Enterprise Editions of Real Studio can create standalone Web applications.
Your choices for the desktop are:
- Windows XP and later: Builds a Windows application that will run on Windows XP and Vista/Windows 7. When you choose this option, the TargetWin32 and TargetX86 compilation options are True.
- Linux with GTK+ 2.x: Builds a Linux application that runs on x86-based machines. Linux builds of Real Studio desktop applications require GTK+ 2.8 or above, glibc-2.3 (or higher), the CUPS (Common UNIX Printing System) and libstdc++.so.6.
For information on GTK, see http://www.gtk.org. Linux builds of console applications do not require GTK. When you choose this option, the TargetLinux and TargetX86 compilation options are True.
- Mac OS X Intel: Builds for the Intel-based Macintoshes in the Mach-O format. MacOS X 10.4 or above is required. When you choose this option, the TargetMacOS, TargetMachO, and TargetX86 compilation options are True. In addition, either the TargetCocoa or TargetCarbon option is True.
All three Macintosh choices use the Mach-O format. Mach is the Unix kernel on which Mac OS X is based and Mach-O is the object file format for Mach. Mach-O is the native executable format for Mac OS X.
Apple created two sets of APIs for Mac OS X: Carbon and Cocoa. Carbon was designed to make it easier for applications originally written for Classic Mac OS (Mac OS 9 and earlier) to be ported to Mac OS X. Cocoa is the name for the API that Apple inherited with NeXTStep which eventually became Mac OS X. Originally, these two APIs were peers on Mac OS X. Over time it has become clear that Carbon is simply a transitional API and that Cocoa is the primary API for the future. Because of this, a new framework for Mac OS X, based on Cocoa, has been added to Real Studio.
When you recompile your application using the Cocoa build option, you will find that most things work as they did before. However, there are some important differences you may need to know about when transitioning your application from the Carbon to the Cocoa build option.
Moving to Cocoa
As of version 2011r4, the Cocoa framework is still in beta stage. Please read the “Cocoa Beta Information.pdf” file in your Real Studio folder at the same level as your Real Studio application.
Use the Paint Event
Using Canvas.Graphics or Window.Graphics directly is very slow under Cocoa. The correct approach is to do your drawing in the Canvas.Paint or Window.Paint events using the Graphics object passed to the event. This does not mean your code must be in the Paint event, just that it gets called from a Paint event. When your Canvas or Window needs to be redrawn, simply call Invalidate.
Don’t Reuse MenuItems
A MenuItem cannot be used in different places at the same time, e.g. if you create a Font MenuItem, you cannot use it in different MenuBars. For this reason, the Clone method has been implemented. You can create a MenuItem and then clone it to use the different copies in different places. The Clone method creates a so-called “deep copy”, i.e. it clones the whole MenuItems hierarchy.
Fonts May Appear Differently
Fonts are rendered differently in Cocoa and the most visible effect is that the line height is different compared to Carbon. At the moment, this may be problematic in Controls because the IDE is still running as a Carbon application while your application is not. The result is that the Controls’ caption may look slightly different in your application compared to how they appear in the Window Editor.
The other thing to be aware of is that in Carbon a font may or may not have variants installed for italic or bold but Carbon can still render these variants. Under Cocoa if the font has an italic variant then Real Studio will be able to use it. If not, it falls back to the non-italic version and it looks incorrect. You can check out what fonts provide by looking at OS X Font Book. This is not a bug in the Real Studio runtime; it is just the way the OS X implementation of font rendering works.
If you need to guarantee that certain fonts exist you can utilize Application specific fonts by following the steps outlined here
Use the System Font
You should not experience problems in control captions if you use the System font, which is the default. As of 2011r2, you may however see differences with SmallSystem font.
Bold and Italic
In Cocoa, only fonts which have a boldface and/or italic-face variations can be displayed as such. You can use the Font Book application to see all the fonts available as well as their variations. You may also have noted that the same limitations apply to Apple's own applications such as TextEdit.
CPU Usage
At the present time, applications built for Cocoa use more CPU time than equivalent Carbon applications. This will be optimized once more urgent issues are addressed. Please do not file a feedback report for such “bugs.”.
See Also
Target Platforms for Web Apps
Compiled Web apps run best on modern open-standards browsers. This includes Apple Safari and Google Chrome. Web applications should also work well in Firefox and in Internet Explorer 7 and above. With Internet Explorer 6.x, users will be unable to run Web apps unless they first install the Chrome Frame extension.
The Chrome Frame extension adds a layer of open-standards web capabilities on top of IE. The result is that IE 6 gains capabilities that are comparable to modern browsers. This includes HTML5 and a current JavaScript engine. For more information about the Chrome Frame extension, see http://code.google.com/chrome/chromeframe/.
Microsoft encourages IE 6 users to upgrade their browser to a more recent version of IE. If a user doesn’t upgrade and tries to run a Real Studio Web app on IE 6.x, a page for installing the Chrome Frame extension will be displayed instead. This screen is shown below.
Users with IE 6 must either install Chrome Frame onto IE 6 or upgrade their browser to a more modern application. After Chrome Frame is installed, the web app should behave normally on IE 6. Users can also solve the problem by using a more recent version of IE, Firefox, or Safari (Windows Service Pack 2 required).
The Stand Alone Build Option
When you build a stand alone web application the result is a standalone web server.
A file named “My Application” and a folder named “Lib” are created. You may place these generated files in any folder for which you have read, write, and execute permissions. “My Application” and “MyLib” must be in the same folder. To use the server, start “My Application” by double-clicking it. In a browser enter the IP address of the computer on which “My Application” is located and the port specified in the build. For example if the machine is 192.168.1.20 and the port was specified as 8080 then you would type 192.168.1.20:8080 in the browser and you should see your web page.
Standalone does not require a separate server such as Apache, the use of Web Sharing, or the use of special directories, e.g. Sites. If the end user is using a browser that supports websockets, then that technology will be used. If not, the connection will be made via AJAX. As of this writing, only Safari and Chrome support websockets, but this may change in the future.
Your web application must have an Application Identifier specified on the App properties or the web application will not start. Typically an application identifier is written using reverse domain name format, such as com.realsoftware.myapp. If you want to run multiple stand alone web applications on the same server, each web application must have a unique Application Identifier.
If you build a Stand Alone Web application and you use the default port of 80, you will need to have root access (Macintosh and Linux) to launch the Web app. In fact, all ports below 1024 require root access. This is a security feature of Unix-based operating sytems. To use the Stand Alone option without root access, choose a port outside the range of 1024 and below, such as port 8080, as shown above.
To do this:
 |
|
Deploying your application as a CGI
With version 2011r1, Real Studio includes a new deployment option simply called “CGI”.
This option builds your application along with a Perl CGI script that will act as a middleman between the web server and your application.
Perl CGI scripts have been nearly universally supported on all web servers for at least 10 years; we believe this option will allow developers to deploy to a wider range of servers than ever before.
The CGI works by attempting to connect to your application and forwarding requests to it. If your application has not been launched, the script will start it first. This design is enormously flexible. If you can run a Real Studio console application on your server, this deployment option will work for you.
When you choose this option in the Build Settings dialog, you will be presented with the option to choose a port, or automatically choose a port for you.
This is the port used to communicate between the script and your application. By having the script choose the port automatically, you reduce the chances of port conflicts. However, you may choose to use a specific port if required by your firewall configurations.
You will need nothing more than an FTP client. When you build your application, you will get the typical folder structure, as well as two additional files: application.cgi and config.cfg, though the CGI will be named to match your application. You may rename the CGI if you choose.
Upload the contents of the folder to your server, to a location that can execute CGI scripts. On many servers, this must be inside a “cgi-bin” folder. You may need to change the permissions of both your application and the CGI script to 755. Consult your FTP client’s documentation for instructions on how to do this.
Once this is done, visit the URL pointing to your CGI script. For example, if you uploaded the folder contents to “public_html/cgi-bin/myapplication/” then your url will be “http://mydomain.com/cgi-bin/myapplication/myapplication.cgi”.
Contents |
CGI on Microsoft Internet Information Server 7 (IIS 7)
Beginning with version 2011r2, a WE app can be served by Microsoft Internet Information Server 7. This section provides the step by step directions for configuringa Vista or Windows 7 desktop or server for a WE app.
To use CGI on IIS7 there are three components that need to come together:
I. An Installation of IIS.
If you are using Microsoft Windows Server, chances are that IIS is already installed and you can skip to step 2[note 1]. If you are using a desktop version of Windows Vista or 7[note 2], follow these instructions to install:
- Launch the Control Panel.
- Click Programs and Features.
- On the sidebar, click Turn Windows Features On or Off.
- At a minimum, you'll need to check the items under Internet Information Service, shown below.
Web Management Tools configuration settings for IIS.
NOTE: It is important that CGI and ISAPI Extensions are installed at this stage.
- Click OK to install the selected components.
II. ActiveState Perl
As the de-facto standard of Perl Installations for IIS, we’ve chosen to document installation of ActivePerl. One downside of ActivePerl is that the 64-bit installer does not include the necessary ISAPI Extension, so you’ll need to download and install the 32-bit version regardless of the type of server you are running. To download, go to http://www.activestate.com/activeperl/. In our testing, we used Windows (x86), version 5.12.3.1204.
- Run the installer you just downloaded.
There is an article[note 3]
on the ActiveState website regarding some changes in IIS7 preventing the ActivePerl installers from completing the configuration.
Run the following line from the command line.
You may need to right+click on the menu to run the command as Administrator.[note 1].
III. IIS configuration.
This part of the configuration is the same for Desktop and Server installations:
- Launch Internet Information Services Manager.
- In the left pane, select your site. If you haven’t configured your site yet, do that now).
- Double-click Handler Mappings.
- On the right sidebar, click Add Script Map.
You will need to configure the Add script Map dialog box as shown here.
- Request Path: *.cgi
- Executable: Browse to the Perl binary folder.
(The default directory is: C:\Perl\bin). Select the file named PerlEx30.dll. - Name: Perl CGI
- Click Request Restrictions
- Mapping: None
- Verbs: All
- Access: Script
- Click OK to put that dialog away.
- Click OK to close that window.
- Click Yes.
You will see a new dialog box with three tab panels.
A dialog will appear asking if you want to allow this ISAPI extension.
- In the left pane, select Application Pools.[note 2]
- Select your site name from the list.
- Click Basic Settings.
- .NET Framework Version: No Managed Code
- Managed pipline mode: Integrated
- Click OK.
If you are on a 64-bit system, do the following:
- Click Advanced Settings.
- Change Enable 32-bit Applications to True.
Your application should be deployed and ready for use.
FastCGI
For added performance, the CGI script can operate as a FastCGI script as well. This should work with mod_fastcgi, mod_fcgid, and any FastCGI-enabled server. However, usage of FastCGI is purely optional. To run your CGI as a FastCGI, simply change the “.cgi” extension of your CGI to your FastCGI extension, which is usually “.fcgi”. FastCGI mode requires the PerlIO::Handle module, and either the “threads” or “Thread” modules. These modules are available on nearly every install of Perl.
FastCGI is not supported for IIS.
Troubleshooting
The CGI will attempt to give you as much information as possible regarding errors, but it sometimes is not helpful.
Internal Server Error
If the CGI is having trouble executing, this message will appear when you try to run your CGI. The error message will be buried somewhere inside the web server error logs. The error is usually a suEXEC policy violation (more information below), or incorrect permissions.
Many hosts run a feature called suEXEC, which allows your CGI and other scripts to be run under your user account, allowing greater security. This is generally a good thing.
However, as part of this feature, CGI scripts placed inside a globally writable directory (777 permissions) will be prevented from running. The folder containing your CGI and app should use 755 permissions.
Unable to launch application
The CGI has executed properly, but was unable to launch your app. More information will follow this error, which is usually a “Permission denied” message. In testing, we have found some shared hosting users receive a “Connection refused” message. This message usually means the hosting provider has a security policy that prevents execution of your app. Check with your hosting provider if you receive this message.
When uploading your application to the server, ensure the app and its libs folder are uploaded in binary mode, everything else in ASCII mode. Many FTP clients get this correct automatically, but some do not.
Application launched, but unable to connect on port #
The CGI was able to launch your app, but was unable to connect to it using the port specified. Your host’s firewall may be blocking this port. You will need to deploy using a static port, and ask your host to open a port for you to use.
Notes
