# Running BoxLang {% hint style="warning" %} Please check out our [installation page ](https://boxlang.ortusbooks.com/getting-started/installation)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. {% endhint %} {% hint style="info" %} The script for \*nix/Mac is `boxlang` The script for Windows is `boxlang.bat` {% endhint %} ### BoxLang Home 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` {% tabs %} {% tab title="Mac" %} ```javascript /Users/username/.boxlang ``` {% endtab %} {% tab title="Linux" %} ```bash /home/username/.boxlang ``` {% endtab %} {% tab title="Windows" %} ```python C:\Users\myuser\.boxlang ``` {% endtab %} {% endtabs %} 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. {% hint style="danger" %} 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. {% endhint %}
Folder/FIleDescription
/classesWhere all the compiled classes will be stored
/configWhere configuration files are stored for the runtime
/config/boxlang.jsonThe runtime configuration file. Here is where you can configure all the settings, caches, datasources, compiler information, and so much more.
/globalWhere global BoxLang classes and component templates can be stored for the entire runtime
/libYou 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.
/logsAll log files will be stored here
/modulesHere is where the BoxLang modules are installed and will be available for the entire operating system binary.
version.propertiesThe version information of the installed runtime.
### Start the REPL 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. {% tabs %} {% tab title="Mac/\*nix" %} ```javascript boxlang ``` {% endtab %} {% tab title="Windows" %} ```ruby boxlang.bat ``` {% endtab %} {% tab title="Jar" %} ``` java -jar path/to/boxlang-1.0.0.jar ``` {% endtab %} {% endtabs %}
You can run one-off expressions from the REPL like so: ```shell Enter an expression, then hit enter. Press Ctrl-C to exit. BoxLang> 2+2 4 BoxLang> dateFormat( now(), "full" ) Wednesday, March 13, 2024 BoxLang> "brad".ucase().reverse() DARB BoxLang> a=3 3 BoxLang> b=5 5 BoxLang> a*b 15 BoxLang> ["luis","gavin","jorge"].map( name->name.ucFirst() ) [Luis, Gavin, Jorge] ``` {% hint style="success" %} Press Ctrl-C to exit the REPL or type `exit` or `quit` {% endhint %} Please note that the REPL remembers state, so you can use the variables you declare and build a mini-program with it. ### Executing a File 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. {% hint style="info" %} Allowed files are: * `*.bx -` A BoxLang class with a `main( args=[] )` method * \*.bxs - A BoxLang script file * \*.bxm - A Boxlang markup template file If you are using the `bx-compat-cfml` module for CFML Support: * \*.cfs - A CFML script file * \*.cfm - A CFML markup template file {% endhint %} 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. {% tabs %} {% tab title="Mac / \*Unix" %} ```bash boxlang task.bx boxlang myscript.bxs boxlang mytemplate.bxm boxlang /full/path/to/test.bxs boxlang /full/path/to/Task.bx ``` {% endtab %} {% tab title="Windows" %} ```powershell boxlang.bat task.bx boxlang.bat myscript.bxs boxlang.bat mytemplate.bxm ``` {% endtab %} {% tab title="Jar" %} ```ruby java -jar boxlang-1.0.0.jar task.bx java -jar boxlang-1.0.0.jar /full/path/to/test.bxs ``` {% endtab %} {% endtabs %} #### Producing Output 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) ```groovy println( "Time is #now()#" ) ``` I get the output: ```bash ╰─ boxlang test.bxs Time is {ts '2024-05-22 22:09:56'} ``` 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. ```groovy class{ function main( args=[] ){ println( "Task called with " & arguments.toString() ) } } ``` You can now call it with zero or more arguments! ```bash ╰─ boxlang Task.bx Task called with {ARGS=[]} ╰─ boxlang Task.bx boxlang rocks Task called with {ARGS=[boxlang, rocks]} ``` ### One Off Code Execution So, to give a quiet example of the `--bx-code` flag here’s running some one-off code. ```bash boxlang --bx-code "2+2" ``` {% hint style="warning" %} This assumes script, not templating tags. {% endhint %} ### Piping code You can also pipe statements into the BoxLang binary for execution as well. This assumes script, not tags. ```bash echo "2+2" | java -jar boxlang-1.0.0.jar echo "2+2" | boxlang ``` or ```bash # on *nix cat test.cfs | java -jar boxlang-1.0.0.jar cat test.cfs | boxlang # on Windows type test.cfs | java -jar boxlang-1.0.0.jar type test.cfs | boxlang.bat ``` ### Printing the Abstract Syntax Tree (AST) BoxLang can emit the parsed **Abstract Syntax Tree** of any source as JSON, which is useful for tooling, debugging, and editor integrations. There are two ways to access the AST. #### Via the CLI Flag Use the `--bx-printAST` flag with any of the three input modes: ```bash # From a file boxlang --bx-printAST /path/to/MyClass.bx # From inline code boxlang --bx-printAST --bx-code "x = 1 + 2" # From stdin cat MyComponent.bx | boxlang --bx-printAST # Integrate with jq for targeted inspection cat MyComponent.bx | boxlang --bx-printAST | jq '.body[0]' ``` #### Via the `boxAST()` BIF You can also retrieve the AST programmatically at runtime using the `boxAST()` built-in function, which returns the JSON AST of any BoxLang source string: ```js ast = boxAST( "result = 1 + 2" ) writeDump( ast ) ``` {% hint style="info" %} The `boxAST()` BIF is useful for meta-programming, code analysis tooling, or any scenario where you need to inspect the structure of BoxLang code at runtime. {% endhint %} ### Command Line Arguments 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. #### Options * `--bx-code "code here"`—This is used to pass ad-hoc code to execute. Provide code in the next argument, quoted. * `--bx-config` - Pass a path to a JSON file for BoxLang configuration. See [Runtime Configuration](https://boxlang.ortusbooks.com/getting-started/configuration) for more information. * `--bx-debug` - Enable debug mode (more debug logs!) * `--bx-home` - Pass a path to a custom runtime home directory for storing modules, configuration, and more. See [Runtime Home Directory](https://boxlang.ortusbooks.com/configuration#runtime-home-directory) for more information. * `--bx-printAST` - Prints out BoxLang AST in JSON format for debugging. Supports three input modes: * **File path**: `boxlang --bx-printAST /path/to/MyClass.bx` * **Inline code**: `boxlang --bx-printAST --bx-code "x = 1 + 2"` * **Stdin piping**: `cat MyComponent.bx | boxlang --bx-printAST` * `--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 #### Positionals * `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 ### Using 3rd Party Jars 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. ### Environment Variables The `boxlang` binary will also scan for several environment variables as overrides to the execution process. | Env Variable | Purpose | | ----------------------------- | ---------------------------- | | `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 | In addition to core runtime OS-level settings, you can also use the environment or Java properties to adjust granular configuration setting. For more [see the Runtime Configuration section](https://boxlang.ortusbooks.com/getting-started/configuration#environmental-properties-configuration).