Running BoxLang
BoxLang and the Multiverse!
Last updated
Was this helpful?
BoxLang and the Multiverse!
Last updated
Was this helpful?
Please check out our to make sure you install the right runtime you want to deploy on. We are assuming you have it installed and boxlang
and boxlang-miniserver
are in your machine's path.
By default, once you execute a boxlang
binary it will look for a BOXLANG_HOME
environment variable so it can be used as the home for the OS runtime. If you don't provide one, then by default, it will use the currently logged-in user's home folder + .boxlang
This is important because inside of the home folder, you can have several folders and files by convention that will be used for the runtime execution.
Please note that each runtime can have a different location for the BoxLang home. So make sure you read each of the runtime's docs to see where each goes.
/classes
Where all the compiled classes will be stored
/config
Where configuration files are stored for the runtime
/config/boxlang.json
/global
Where global BoxLang classes and component templates can be stored for the entire runtime
/lib
You can place any *.jar files here, and they will be loaded into the runtime at startup. This is a great place to put third-party jars that will be available at runtime.
/logs
All log files will be stored here
/modules
Here is where the BoxLang modules are installed and will be available for the entire operating system binary.
version.properties
The version information of the installed runtime.
The first thing you can do is start up the BoxLang REPL, make sure the insaller has added your installation directory to the PATH
system variable.
You can run one-off expressions from the REPL like so:
Press Ctrl-C to exit the REPL or type exit
or quit
Please note that the REPL remembers state, so you can use the variables you declare and build a mini-program with it.
You can also use the boxlang
binary to execute BoxLang or even CFML code. You can pass a second argument to the binary and it can be a relative (to the current directory you are on) or an absolute path to a file that you wish to execute.
Modify the same command you run above to execute the REPL but add a file path to the end. It can be absolute or relative to the current working directory.
As you navigate all the built-in functions and capabilities of BoxLang, let's learn how to produce output to the system console.
printLn()
- Print with a line break
print()
- Print with no line break
writeOutput()
- Writes to the output buffer (Each runtime decides what it's buffer is. The CLI is the system output, the Web is the HTML response buffer, etc)
I get the output:
Hooray! You have executed your first script using BoxLang. Now let's build a class with a main( args=[] )
convention. This is simliar to Java or Groovy.
You can now call it with zero or more arguments!
So, to give a quiet example of the --bx-code
flag here’s running some one-off code.
This assumes script, not templating tags.
You can also pipe statements into the BoxLang binary for execution as well. This assumes script, not tags.
or
If you interact with the boxlang
binary then you will be executing the BoxRunner
class in BoxLang. You can use several options and positional arguments to our runtime. Let's explore them.
--bx-code "code here"
—This is used to pass ad-hoc code to execute. Provide code in the next argument, quoted.
--bx-debug
- Enable debug mode (more debug logs!)
--bx-printAST
- Prints out BoxLang AST in JSON format for code provided via the -c
flag (for debugging)
--bx-transpile
- Prints out transpiled Java source that would be compiled to create the bytecode for the passed template path. (for debugging)
--version
- Output the current runtime's version information
script_path | class_path
- The template, class, or script to execute
If it's a class, it must have a main( args )
method.
module:{name}
- The executable module to execute. This will execute a Modules' ModuleConfig.main( args )
method.
{actionCommand: compile,featureAudit, cftranspile}
- If you send any of those action commands, we will execute those CLI tools
You can load custom third-party JARs at runtime by adding all your *.jar
to the BOXLANG_HOME/lib
folder. This will be loaded at runtime and available to use and integrate.
The boxlang
binary will also scan for several environment variables as overrides to the execution process.
BOXLANG_CONFIG
= PATH
Override the boxlang.json
BOXLANG_DEBUG = BOOLEAN
Enable or disable debug mode
BOXLANG_HOME = DIRECTORY
Override the HOME directory
BOXLANG_PRINTAST = BOOLEAN
Print the AST
BOXLANG_TRANSPILE = BOOLEAN
Tranpile the code
The . Here is where you can configure all the settings, caches, datasources, compiler information, and so much more.
--bx-config
- Pass a path to a JSON file for BoxLang configuration. See for more information.
--bx-home
- Pass a path to a custom runtime home directory for storing modules, configuration, and more. See for more information.
In addition to core runtime OS-level settings, you can also use the environment or Java properties to adjust granular configuration setting. For more .