AppBuilder 2.0 - User Guide
This document describes how you can manage and build your Hollywood projects using the AppBuilder application.
Terms and Conditions
APPBuilder is © Copyright 2015-2017 by Fabio Falcucci (in the following referred to as “the author”). All rights reserved. The program is provided “as-is” and the author can not be made responsible of any possible harm done by it. You are using this program absolutely at your own risk. No warranties are implied or given by the author.
It is forbidden to spread this program without a written permission of the author.
DISCLAIMER: THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
If you have purchased this application you can write me for e-mail support, bug reports and feature suggestions at :
You can also ask in the support forum to report bugs, get help or to suggest ner features.
I'm an Hollywood developer, Hollywood is a cross-compiling multimedia language developed by Andreas Falkenhahn, and actually I'm working on several projects each with its own additional files a plugins. During the building process it was a pain for me to manage and remember all files, and plugins I had to include in the application bundle for each platform I wanted to target, so I started this application called APPBuilder that helps with this process.
The main purpose of AppBuilder is to simplify the build process taking care of all additional files and plugins for each targeted platform with the option to pack all the included stuff into a zipped archive.
Once you have defined your application project, with a single click of a button, you will be able to start the build process. After working on your code you can load the previously saved project and click the build button and all the boring stuff like including readme, resource data and plugins for the appropriate platform will became old story.
APPBuilder will manage for you also the MacOSX application boundles copying your application data in the right folders.
- Hollywood : This is obvious if you want to build Hollywood projects - Screen resolution : 800×600 or greater - 7zip installed on your system : This is needed if you want to pack your application builds in zipped archives - Classic Amiga RTG and extra memory are supported That's all.
APPBuilder does not need any installation procedure, you have to unpack the compressed archive you have downloaded into a folder of your choice. Once extracted the contents, you should find in the destination folder the following items:
- AppBuilder executable (This is the main program, the one you have to execute to start the application)
- config (This file is used by APPBuilder to store its configuration)
- licenses (This folder holds all plugins licenses)
- plugins (Here are all plugins available at release time)
To uninstall APPBuilder just delete the folder that holds the application and you are done.
When you execute for the first time AppBuilder it will ask you to download all available plugins from a remote server, this step is necessary to include the plugins in your compiled application packages. All this files will be saved in the <plugins> directory.
Please wait until all the plugins for all available target OSes are downloaded, it will require some time depending on your Internet speed, it also get around 180Mb of your hard-disk space.
Once the download process has been completed you will get a requester asking to configure the applicaiton, the information needed are the following:
- Hollywood executable location
- 7Zip executable (only needed if you want to pack your compiled packages)
- Plugin folder (default to plugin folder inside your app folder)
- You can also change the language selecting one from the drop down gadget.
SAVE PREFERENCES button to write your preferences.
Now you are ready to create your first project.
APPBuilder use a simple interface that allow you to have all under your control and all options always visible, what you see in the main interface is what you have at your fingertips to build your applications.
Let's see a picture of APPBuilder (Windows version, v2.0) :
You will get this interface when you run the program.
As you can see the main window is divided in two big sections, the left one, with copper buttons, are used to manage the current project, while the right side is dedicated to the project editing.
The left side, the one with copper buttons, have all you need to manage your projects
Starting from the left-top buttons column you can see a group called
This group holds four buttons with the following functions:
- LOAD : To load a previously saved project
- SAVE : To save the current project to a file
- SAVE AS : To save the current project to a file using a new file name
- CLEAN : To clean up the current project (without touching the saved project)
The second group you can find is called flags, and have only two switches:
- COMPRESSION : If activated (switch is down) your project will be compiled using the -compress flag to produce a smaller executable.
- PACK : If activated (switch is down) your project will be packed into a single ZIP file, for this feature you need to have 7Zip installed in your system. and configured in the AppBuilder.
The third section holds four buttons as showed below:
- UPDATE : Check if there are plugin updates or if a new AppBuilder version is available.
- CONFIGURE : Open the configuration window.
- ABOUT : Open a window with some informations about AppBuilder.
- WEBSITE & DOCS : Open your browser to the web page of this application.
The last button you have is the BUILD button:
Clicking this button will start the build process. A status window will be opened so you will be able to view what's happening. Have a look at the tutorial for a complete explanation.
The top right section is where you can describe and setup your project, here are the available fields with a brief descriotion :
- PROJECT NAME : Type here the project name you are creating / editing
- MAIN SOURCE : Type or select with the three-dots button the main source you wish to compile (*.hws script)
- EXECUTABLE NAME : Here you can type the base name that will be used to build your application, an .exe extension will be added automatically for Windows executables, you have to specify just the path and name without any extension.
- .INFO ICON : This field is usefull if you are compiling for Amiga-like systems, it will include the provided info-file (renaming it if necessary) with the generated executable. This means that you can use an info-file with an arbitrary name, APPBuilder will take care to copy this file in the appropriate place with the appropriate name.
- NOTES : This is a free field you can use to write notes about this project. If you need to insert a newline just hit Left Shift + Enter because hitting Enter will close the input field.
Notes about the EXECUTABLE NAME field: If you do not specify any path the builds will be generated in the APPBuilder directory otherwise it will be generated in the specified path.
Example: Suppose you want to generate an executable called Proggy, if you specify just Proggy in the Executable name field the build will be generated in the APPBuilder directory, but if you provide a path like C:/Development/Proggy/builds/Proggy the build will be generated in C:/Development/Proggy/builds/ using the name Proggy for the executable.
The bottom right section is divided in smaller areas, starting from the left you can see a group of switches called Targets, here you can select for which platform you wish to build your project, every target supported by Hollywood 7 has been provided. Just select the switches for which you need to compile your program and you are done, don't forget to save your project so next time you will open it these switches will be recalled and selected for you.
Your application may need one or more plugins to work, and each supported platform has its own plugin version. Moreover the position where the plugin must be copied is not the same for OSX application boundles. If you are used to develop application for all Hollywood supported platforms you know the pain when you need to prepare the distribution packages.
AppBuilder make all of this a joke because all available plugins are listed in the middle lower section of the interface, you only have to select which plugin to include and AppBuilder will do the rest at building stage. If you have selected a plugin not available for a platform you have selected as a target, during the build process, a requester will alert you, but the building will not be interrupted.
Just selected the plugin your application uses and at build time they will be copied into the appropriate folder.
Your application may need some resource files like images, sounds, databases, that are needed at runtime. You have to include this data in the distribution packages the let your app make use of it.
Here is an example: Suppose you are devolping a game that uses the following resources: C:/Development/MyGame/Graphics/ C:/Development/MyGame/Sounds/ C:/Development/MyGame/Maps/ C:/Development/MyGame/levels.dat
In a manual build process you should copy the folders Graphics, Sounds and Maps, along with the file levels.dat where your executable has been compiled. This must be done for every platform you wish to compile for.
This section helps a lot to accomplish this task because you have to tell APPBuilder what to include in your distribution and at build time AppBuilder will take care of copying the contents in the right position, including OSX application boundles management.
As you can see, at the bottom side of the resources area, you have three buttons you can use to add files, to add folders (and their contents) and to remove entries from the resources list.
External data is anything you want to distribute with you application but that's not needed bvy the application to run, an example could be a readme.txt file and documentation files. All files and folders you will include into this category will be packed outside the application folder for easy accessibility by the final user.
Like what you have seen for the resources area, you have two buttons to add files and folders in the external data group and a button to remove a previously selected entry.
Building Your Apps
When you have finished to setup a project to build, or you have recalled one with the LOAD button you can hit the BUILD button to build your application with the appropriate plugins and application data (both resources and external data).
Here the file structure generated by the building process:
[ build folder ]
+— [ build date and time ]
+— [ platform name ]
| +– [ external data ]
| [ application folder ]
| +— [ application executable ]
| [ application resources ]
| [ plugins ]
+— [ platform name ]
The above chart is for all platforms excluding the MacOS X because this system needs a particular folder structure called App Bundle and it is listed below:
[ build folder ]
+— [ build date and time ]
+— [ platform name ]
| +— [ application folder ]
| +— [ external data ]
| [ application boundle ]
| +— [ Contents ]
| +— [ MacOS ]
| | |
| | +— [ plugins ]
| | [ application executable ]
| +— [ Resources ]
| +— [ application resources ]
+— [ platform name ]
AppBuilder will manage for you MacOS X app bundles without any efforts from you.
Your First Project
Let's see how you can use AppBuilder to manage (and build) a project.
First of all create an Hollywood script, when you have completed your script and you are ready to build your packages, open AppBuilder and click CLEAN button to clean-up all the available fields.
DESCRIBE YOUR PROJECT
- Give your project a name
- Select the main source code of your application
- Set the executable name and the path where AppBuilder should build the packages
- Select an .info icon if you are targetting also Amiga-like systems (optional)
- Type some notes about your project (optional)
SELECT THE BUILD TARGETS
- Push down the switches that identifies your target platforms
SELECT THE NEEDED PLUGINS
- Push down the switches that identifies the plugins used by your application
SPECIFY APPLICATION RESOURCES*
- Add any data file and/or folders used as resources by your application
SPECIFY EXTERNAL DATA*
- Add any data file and/or folders used as externat data
- Chose if the executable must be compiled using the -compress flag to produce a reduced in size executable (switch COMPRESS)
- Chose if you want to pack each platform builds into a single zipped archive (switch PACK)
SAVE YOUR APPBUILDER PROJECT*
- Hit SAVE or SAVE AS button to save this project if you plan to build again your just created project
B U I L D !
- Hit the BUILD button and wait for the process to be completed
During the building process you will see a window showing the progresses and, depending on your 7zip version, a window showing the packing progresses. You can also get some messages while building, for example if you are trying to use a plugin that is not available for a target platform a requester will warn you about this problem but the build process will not be stopped to allow all your selected targets to be built despite the one having problems.
Once you have updated your Hollywood program and are you ready to compile a new version just launch AppBuilder, LOAD your previously saved project, adjust it adding/removing resources, externale data, plugins, and so on… SAVE it and BUILD.
You will became more productive using this tool and you will reduce risks to forget out of the package plugins or application data, or even to distribute with your application a plugin for the wrong target platform.