Manage Data Your Way
Creating BarracudaDrive Applications
BarracudaDrive is designed for non-technical users, so you do not need to know anything about programming when installing or using BarracudaDrive. This tutorial is intended for programmers who want to tinker, customize, or write new applications for BarracudaDrive.
Easy to learn scripting language for beginners to hardcore programmers
You will have to learn the Lua language and server side web development if you plan on writing your own applications, but you do not have to write any low level C or C++ code. However, users with C/C++ experience can optionally extend the server with new functionality by loading additional C libraries at runtime.
The Lua Scripting Language
Lua Server Pages makes developing web applications extremely fast, simple, safe, and fun. Notably, it isn't limited to developing web applications, but can also be used to provide high-level socket APIs that make developing secure socket applications very easy. We also provide HTTP client libraries, SMTP (mail) libraries, database integration (SQLite is embedded in BarracudaDrive), and other options.
Lua Server Pages are based on the Lua Scripting Language. Getting started with LSP is easy if you have previous experience with similar technologies such as PHP or ASP.
The about BarracudaDrive page includes an introduction to how BarracudaDrive is assembled, and explains how this consumer product was developed using the Barracuda Application Server "C" library. Real Time Logic's core business is to provide this C library to engineering companies, who in turn embed the code in device firmware.
As illustrated in the figure to the right, the BarracudaDrive server's two main components are the generic Barracuda Application Server "C" Library and the C/C++ code designed specifically for BarracudaDrive. In addition, a number of LSP applications are bundled with BarracudaDrive such as the CMS and the forum. The LSP applications are delivered as source code, so you are free to study and modify this code. See the BarracudaDrive Parts List for a detailed explanation of all parts delivered with BarracudaDrive.
Lua Server Pages Programming API
since BarracudaDrive is developed by using the Barracuda Application Server C Library, all of the Barracuda Application Server's Lua API's are supported, enabling you to write anything from easy to advanced server side web applications.
Application Server and Lua
We recommend reading the Barracuda Application Server article What is an Application Server? if you are uncertain about the difference between a web server and an application server or if you are new to writing server side web applications. We also recommend reading the Lua fast-tracks web application development article if you are new to Lua and web design.
Dynamically Generated Pages
Lua Server Pages (LSP) can be freely intermixed with HTML or XML. LSP tags are XML compliant
LSP Page Counter Example:
<?lsp page.count=page.count and page.count+1 or 1 ?> <html> <body> <p> You are visitor <?lsp=page.count?>. </p> </body> </html>
BarracudaDrive provides Lua bindings (interface from Lua to C code) for the following integrated components: the Barracuda Application Server, SharkSSL SSL/TLS duo stack, Lua Server Pages, SMTP Client, HTTP(S) Client, AJAX, JSON, JSON-RPC, XML-RPC, SOAP Web Services, WebDAV Server, the EventHandler, High Level Secure Sockets, the SQLite Database, the GD Graphics Library, and Lua LPeg. You can dynamically load additional Lua bindings at runtime such as an API to your own hardware, but this requires that you also master C code.
Getting Started With LSP
To get started with BarracudaDrive, install the server on your own computer, but skip the Internet Wizard. The server you install on your own computer will be your test server. You can start developing LSP applications as soon as you have installed the server, but we recommend that you download the API documentation and complete a tutorial before attempting to write any LSP applications.
- Download and install BarracudaDrive.
- Download the "Barracuda Application Server" documentation badoc.zip.
- Download the "Do It Yourself" tutorial diy.zip.
- Move the two downloaded files badoc.zip and diy.zip to the BarracudaDrive application directory. The BarracudaDrive's application directory can be found as a sub-directory in the BarracudaDrive installation directory.
- Using a browser, navigate to BarracudaDrive, menu, Administrator Panel, Application Manager, Load, and click the load button to load badoc.zip and diy.zip.
- BarracudaDrive will add links to the left menu, under section "Loaded Applications" for the documentation and the Do It Yourself Tutorial.
- Using BarracudaDrive, complete the Do It Yourself Tutorial and use the loaded documentation for reference.
Using LSP in BarracudaDrive
You have three options when it comes to writing LSP applications in BarracudaDrive.
- Use the CMS and add LSP directly into the CMS pages.
- Add LSP files to the cmsdocs directory.
- Create a new BarracudaDrive application.
|Option one is for programmers who want to add basic LSP scripts to web pages created using the CMS. Snippets of LSP code can be added to any page in the CMS by using the CMS editor. However, you cannot currently use the WYSIWYG editor. Open the editor for the page you want to LSP enable and click the advanced button. You will see the HTML code. Enable LSP in the check box at the top. Add your LSP code to the page. The code is automatically executed each time you press the save button.|
Option two is for applications that should be an integral part of the CMS web pages. You can add LSP pages directly to the cmsdocs directory and/or to any sub-directory in the cmsdocs directory. For example, creating index.lsp in sub-directory 'shopping' can be access as http://my-server/shopping/ and http://my-server/shopping/index.lsp. Be careful with creating pages with the same name as pages in the CMS. Your own pages take precedence over pages in the CMS. For example, adding page index.lsp directly in the cmsdocs directory replaces the CMS main page when you navigate to your server.
Option three is for standalone or advanced applications. How to create and load new applications are briefly explained in the BarracudaDrive help-file under Administrator Panel, Application Manager, New.
When you create a new application you must first create a new sub directory in the BarracudaDrive installation directory. This directory will be the base for your application. In other words, the web pages for your application are stored in this directory. Using a browser, navigate to BarracudaDrive, menu, Administrator Panel, Application Manager, New. Click the browse button, browse and select your newly created directory. Use the directory name as the "Application Name" and click Submit. On the next page, select LSP and click Submit.
When creating a new application, you will get the option of creating a regular application or a root application. A root application is as the name implies, an application that starts with the URI /. For example, an index.lsp page in the application folder is accessible as http://myserver/. A standard application starts with the base name you selected as the application name. For example, an application named myapp and with index.lsp in the application folder is accessible as http://myserver/myapp/
The CMS delivered with the BarracudaDrive server is configured as a root application. You can easily verify that the CMS is a root application by navigating to http://myserver/. You should see the CMS main page.
BarracudaDrive can load multiple root applications. Resource (name) conflicts are resolved by the application's priority. For example, two root applications with an index.lsp are resolved by executing the index.lsp page in the application with the highest priority. You can dynamically change the priority for any root application by clicking on the root application name in the BarracudaDrive's application list. Note: you can only change the priority for root applications in BarracudaDrive.
You can optionally deploy an application when you have completed the development. Deploying an application is done by zipping all pages and data in your application directory and placing the ZIP file in the BarracudaDrive "applications" folder. Using a browser, navigate to menu, Administrator Panel, Application Manager and stop the development version. Click the Load menu link and then click the load button to load your newly deployed application.
You can also unpack any of the BarracudaDrive applications such as the CMS. You can that way easily modify any of the applications that are delivered with BarracudaDrive. Copy the unpacked content to a new directory and use the Application manager to load the non deployed application. Follow the steps above for creating a new application when loading a non deployed application.
You can remove the LSP applications delivered with BarracudaDrive if you want a complete custom solution. However, the internal user interface (uri /rtl/) cannot be removed. The server will not start if it is unable to load bd.zip.
Creating libraries, re-usable code, or non web applications
At this point you are ready to make your first LSP application(s). The rest of this document is tailored for advanced application design.
BarracudaDrive has the concept of an application environment. The environment for an application is a location where you can keep commonly used Lua code i.e. library functions. This environment is available to LSP pages in the application, but not to LSP pages in other applications. The application environment is referred to as the application table in our documentation. BarracudaDrive provides a number of environments that can be used by LSP programmers. See the "Lua -> overview" in the Barracuda document for more information.
The Lua code is typically not embedded in LSP pages if you write functions that are designed to be re-used by several LSP pages or if you write Lua code that is using the more advanced features of the Barracuda Application Server API's. BarracudaDrive looks for the file ".preload" when loading applications. You can place your generic functions in this file as well as any code that is not directly associated with a web page.
Functions and data in the .preload script are added to the application table. You can access this table from an LSP page as "app". For example a function such as myfunc() can be accessed from an LSP page as app.myfunc().
The .preload scripts are executed when BarracudaDrive starts and when an application is started by using the BarracudaDrive Application Manager. You can use the Application Manager to load your new version at any time during development. Click the stop button and then the start button to reload the script.
When an application is stopped by BarracudaDrive, code in the .preload script will eventually become garbage collected by the Lua virtual machine. However, sometimes you may want to do an immediate action when an application is stopped. BarracudaDrive looks for the function "onunload()" just before stopping an application and executes this function if you have created such a function in your .preload script.
The CMS is a deployed application that has a .preload script internally located in the ZIP file. This file is executed by BarracudaDrive when the CMS starts. The CMS preload script is in turn looking for a .preload script in the cmsdocs directory. You can extend or add your own functions to the CMS by creating a .preload script in the cmsdocs directory. For example, adding a function such as myfunc() to the .preload script in the cmsdocs/ directory can be accessed from LSP enabled CMS pages and LSP pages in the cmsdocs/ directory as app.myfunc().
CMS .preload script example
The following example shows how you can create a custom 404 handler by creating a text file cmsdocs/.preload in an editor and then copying and pasting the following Lua code into the .preload script.
The above example is specifically designed for the CMS .preload script. The cmsdocs directory is chained in such a way that response:forward() cannot find files in the cmsdocs directory. We have to use response:redirect() as an alternate solution. Notice how we have the special construction that prevents recursive calls.
Note: the cmsdocs/my404.lsp must be an LSP page that includes the following LSP code:
<?lsp response:setstatus(404) ?>
Modifying BarracudaDrive's Internal Resources
Starting with BarracudaDrive (BD) 6.0, the server's internal resources can be loaded in non deployed mode. The resource files are located in bd.zip. The following instructions are for unpacking this ZIP file and for requesting BD to load the unpacked (non deployed) resources.
- In the BD installation directory, create a new sub directory such as bdzip.
- Unzip bd.zip into this directory.
- Open a command window in the BD installation directory.
- Set the environment variable BD_ZIP=bdzip, where bdzip is the directory where you unpacked bd.zip. For example, use the following command on Windows: set BD_ZIP=bdzip.
- Start BD as a foreground process on the command line. For example, use the following command on Windows: bd -console.
- You can now actively edit and modify the BD resources using an editor. Pressing the refresh button in the browser reloads your modified content.
Separating Re-Usable Code Into Several Files
If you have an advanced application, you may want to create several files where you keep your generic code instead of adding all code to the .preload script. You can make the .preload script load this code by using methods in the Barracuda Application Server API. Look up the function baio:dofile() in the I/O interface.
Standard Lua uses the function "require" when loading global library functions. You can read up on "require" in the Lua book. In BarracudaDrive, "require" looks for files in the ".lua" directory inside bd.zip, so you cannot use require for your own files unless you add your own Lua loader. You can add your own Lua loader plugin to your application by using the following code:
local function createLoader(io) function loader(name) local lname=name..".lua" if not io:stat(lname) then -- Package could be "compound1.compound2" local dir dir,name = name:match("(%w+)%.(%w+)") if not dir then return nil end lname=string.format("%s/%s.lua",dir,name) if not io:stat(lname) then return nil end end return io:loadfile(lname) end -- Add to 'loaders' used by 'require'. See Lua doc for more info. table.insert(package.searchers, loader) end -- Example -- Add a loader that uses my own application I/O -- createLoader(io) -- io is defined in my app i.e. in .preload -- Add a loader that loads using the network file system local nio = ba.mkio(ba.openio("net"),"http://my-far-side-server/mydir/") createLoader(ba.mkio(nio))
Extending BarracudaDrive with Custom C or C++ Code
Beginning with BarracudaDrive 5.3, the Lua to C API in BarracudaDrive (lua bindings) can be extended. Shared libraries (DLLS on Windows) can be dynamically loaded by Lua scripts at runtime. Loading shared libraries at runtime is in Lua terminology called loading a module and is performed by calling require("module-name") from a Lua script or LSP page.
Building C modules is an option available to developers with C experience. A Lua C module makes it possible to extend the server's API with new functions. For example, you can add new Lua functions that accesses your serial or USB driver and that makes it possible to manage hardware via a web based user interface. Building modules for BarracudaDrive is identical to building modules for the Mako Server. See Building C/C++ Modules for the Mako Server for more information.