Engee documentation

Command Line Interface

Using arguments inside scripts

When you run the script using julia, you can pass additional arguments to it.:

$ julia script.jl arg1 arg2...

These additional command line arguments are passed in the global constant ARGS'. The name of the script itself is passed in the global constant `PROGRAM_FILE'. Please note: the 'ARGS constant is also set when calculating the Julia expression passed via the command line using the -e parameter (see the output of the julia help below), but the PROGRAM_FILE constant will be empty. For example, you can output only the arguments passed to the script like this.

$ julia -e 'println(PROGRAM_FILE); for x in ARGS; println(x); end' foo bar

foo
bar

This code can also be placed in a script and run:

$ echo 'println(PROGRAM_FILE); for x in ARGS; println(x); end' > script.jl
$ julia script.jl foo bar
script.jl
foo
bar

Using the '--` separator, you can separate the command-line arguments intended for the script file from the arguments intended for Julia.:

$ julia --color=yes -O -- script.jl arg1 arg2..

For more information about writing Julia scripts, see Scripts.

The entry point is Main.main

Starting from Julia (1.11), Base exports the macro @main'. This macro expands to the character `main, but upon completion of the script or expression execution, julia will attempt to execute the function Main.main(ARGS) if such a function has been defined and this behavior has been selected using the macro @main.

This feature is designed to help unify compiled and interactive workflows. In compiled workflows, the loading of the code defining the main function can be spatially and temporarily separated from its call. However, for interactive workflows, this behavior is similar to explicitly calling exit(main(ARGS)) at the end of the script or expression being defined.

Compatibility: Julia 1.11

The special entry point Main.main was added in Julia 1.11. For compatibility with previous versions of Julia, add an explicit macro @isdefined(var"@main") ? (@main) : exit(main(ARGS)) at the end of the scripts.

To see this feature in action, consider the following definition, which executes the print function, despite the absence of an explicit call to main:

$ julia -e '(@main)(args) = println("Hello World!")'
Hello World!

This applies only to the binding of main in the Main module and only if the macro @main was used in the defining module.

For example, if you use hello instead of main, the hello function will not be executed.:

$ julia -e 'hello(ARGS) = println("Hello World!")'

as well as the simple definition of main:

$ julia -e 'main(ARGS) = println("Hello World!")'

However, it is not necessary that acceptance takes place during the definition.:

$ julia -e 'main(ARGS) = println("Hello World!"); @main'
Hello World!

The main binding can be imported from the package. The hello world package, defined as follows:

module Hello

export main
(@main)(args) = println("Hello from the package!")

end

can be used as shown below:

 $ julia -e 'using Hello'
 Hello from the package!
$ julia -e 'import Hello' # Note. The execution depends on the binding, not on whether the package is loaded.

However, please note that it is currently recommended not to mix the application code and a reusable library in the same package. Auxiliary helper applications can be distributed as separate packages or as scripts with separate entry points main in the bin folder of the package.

Parallel mode

Julia can be run in parallel mode using the '-p` or --machine-file option. The '-pn` parameter starts an additional n workflows, and the --machine-file file starts a workflow for each line in the file file. The computers specified in the file argument must be accessible via ssh without a password, and the Julia environment must be installed at the location of the current host. Each computer is specified in the following form: [count*][user@]host[:port] [bind_addr[:port]]'. By default, `user is the current user, and port is the standard SSH port. count is the number of worker processes spawned on a node (1 by default). The optional bind-to bind_addr[:port] element defines the IP address and port that other worker processes should use to connect to this process.

Launch file

The code that should be executed each time Julia is started can be placed in the file ~/.julia/config/startup.jl:

$ echo 'println("Greetings! 你好! 안녕하세요?")' > ~/.julia/config/startup.jl
$ julia
Greetings! 你好! 안녕하세요?

...

Please note: the directory ~/.julia must exist after the first launch of Julia, however, the folder ~/.julia/config and the file ~/.julia/config/startup.jl may need to be created manually.

So that the startup code is executed only in REPL Julia (and, for example, not when running julia in the script), use atreplinit in startup.jl:

atreplinit() do repl
    # ...
end

Command Line Options for Julia

Just like programs in perl and ruby, there are different ways to run Julia code with parameters.:

julia [switches] -- [programfile] [args...]

The following is a complete list of command-line options available at Julia startup (the "*" symbol marks the default value, if any; options marked "($)" can initiate pre-compilation of the package).

Parameter Description

-v, --version

Displays information about the version.

-h, --help

Outputs command line parameters (the contents of this table).

--help-hidden

Displays rare parameters that are not displayed when using the '-h` parameter.

--project[={<dir>|@.}]

Sets the directory <dir> as the active project or environment. When using the default value @. the file Project.toml or JuliaProject.toml is being searched in the parent directories.

-J, --sysimage <file>

Launching using the specified system image file

-H, --home <dir>

Sets the location of the `julia' executable file.

--startup-file={yes*|no}

Downloads the file JULIA_DEPOT_PATH/config/startup.jl. If the environment variable is JULIA_DEPOT_PATH' is not set, downloads the file `~/.julia/config/startup.jl.

--handle-signals={yes*|no}

Enables or disables Julia signal handlers by default.

--sysimage-native-code={yes*|no}

Uses machine code from the system image, if available.

--compiled-modules={yes*|no|existing|strict}

Enables or disables incremental pre-compilation of modules. The existing parameter allows the use of existing compiled modules that were previously precompiled, but prohibits the creation of new precompilation files. The strict parameter is similar, but if there is no pre-compilation file, an error will occur.

--pkgimages={yes*|no|existing}

Enables or disables the use of machine code caching in the pkgimages form. The existing parameter allows you to use existing pkgimages, but prohibits the creation of new ones.

-e, --eval <expr>

Evaluates the expression <expr>.

-E, --print <expr>

Evaluates the expression <expr> and outputs the result.

-m, --module <Package> [args]

Executes the entry point Package' (function `@main) with `args'.

-L, --load <file>

Immediately loads the file <file> on all processors.

-t, --threads {auto|N[,auto|M]}

Activates N[+M] threads. N threads are assigned to the default thread pool, and if M is specified, then M threads are assigned to the interactive thread pool. With the value auto, an attempt is made to output the appropriate number of default streams, but the behavior features may change in the future. Currently, N is set equal to the number of CPUs assigned to a given Julia process via the OS-specific binding interface (Linux or Windows), if supported, or equal to the number of CPU threads if this interface is not supported (macOS) or if process binding is not configured. M is set to 1.

--gcthreads=N[,M]

Use N threads for the tagging stage during garbage collection and M threads (0 or 1) for the parallel cleanup stage. N is set to half the number of computing threads, and M is set to 0, unless otherwise specified.

-p, --procs {N|auto}

Starts N additional local workflows (N is an integer). When using the auto value, the number of running worker processes is equal to the number of local CPU threads (logical cores).

--machine-file <file>

Runs processes on the nodes listed in `<file>'.

-i, --interactive

Interactive mode; REPL is running, isinteractive() is set to true.

-q, --quiet

Running without messages: the banner is not displayed, the REPL warnings are hidden.

--banner={yes|no|short|auto*}

Enables or disables the loading banner.

--color={yes|no|auto*}

Enables or disables colored text.

--history-file={yes*|no}

Downloads or saves the history.

--depwarn={yes|no*|error}

Enables or disables warnings about syntax and method decommissioning (errors are displayed instead of warnings when using the error value).

--warn-overwrite={yes|no*}

Enables or disables warnings about overwriting methods.

--warn-scope={yes*|no}

Enables or disables a warning about an ambiguous top-level area.

-C, --cpu-target <target>

Limits the use of CPU functions at the <target> level. To view the available options, set the value to `help'.

-O, --optimize={0|1|2*|3}

Specifies the optimization level (level 3 if the -O parameter is used without specifying the level) ($).

--min-optlevel={0*|1|2|3}

Sets the lower bound for optimization at the module level.

-g, --debug-info={0|1*|2}

Specifies the level of debugging information to be created (level 2 if the -g parameter is used without specifying the level) ($).

--inline={yes|no}

Determines whether embedding is allowed, including redefining @inline declarations.

--check-bounds={yes|no|auto*}

Determines whether boundary checks are always performed, never, or with consideration for @inbounds ($) declarations.

--math-mode={ieee,fast}

Enables or disables unsafe optimizations of floating-point values (overrides the @fastmath declaration).

--polly={yes*|no}

Enables or disables the polyhedral Polly optimizer (overrides the @polly declaration).

--code-coverage[={none*|user|all}]

Counts the number of source code line executions (if no value is specified, the value user is used).

--code-coverage=@<path>

Counts the executions, but only in files located on the specified path or in the specified directory. The prefix @ is required to select this parameter. If there is no path after the `@' character, the current directory is tracked.

--code-coverage=tracefile.info

Adds code coverage information to the LCOV trace file (the file name supports format tokens).

--track-allocation[={none*|user|all}]

Counts the number of bytes allocated by each line of the source code (if no value is specified, the user value is used).

--track-allocation=@<path>

Counts bytes, but only in files located at the specified path or in the specified directory. The prefix @ is required to select this parameter. If there is no path after the `@' character, the current directory is tracked.

--bug-report=KIND

Starts an error reporting session. It can be used to run a REPL, execute a script, or evaluate expressions. First, it tries to use the BugReporting file.the jl installed in the current environment. If the attempt fails, the latest compatible BugReporting.jl file is applied. For more information, see the description of the --bug-report=help parameter.

--heap-size-hint=<size>

It forcibly starts garbage collection if the memory usage exceeds the set value. The value can be specified as a number of bytes (including KB, MB, GB, or TB) or as a percentage (%) of the amount of physical memory.

--compile={yes*|no|all|min}

Enables or disables the JIT compiler, or requests an exhaustive or minimal compilation.

--output-o <name>

Creates an object file (including system image data).

--output-ji <name>

Creates a system image data file (.ji).

--strip-metadata

Deletes docstring strings and source code location information from the system image.

--strip-ir

Removes the intermediate representation (IR) of compiled functions.

--output-unopt-bc <name>

Creates an unoptimized LLVM bitcode (.bc).

--output-bc <name>

Creates an LLVM bitcode (.bc).

--output-asm <name>

Creates an assembly file (.s).

--output-incremental={yes|no*}

Creates an additional (incomplete) output data file.

--trace-compile={stderr|name}

Displays precompilation statements for methods compiled at runtime, or saves them to the specified path.

--image-codegen

Forcibly generates the code in the image creation mode.

--permalloc-pkgimg={yes|no*}

Copies the package image data section to memory.
Compatibility: Julia 1.1

In Julia 1.0, when using the --project=@' parameter. by default, the Project.toml file was not searched from the root directory of the Git repository. Starting from version Julia 1.1, such a search is performed.