.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH CASTLE-ENGINE "1" "April 2023" "Castle Game Engine" "User Commands"
.SH NAME
castle-engine \- build and package Castle Game Engine programs
.SH DESCRIPTION
castle\-engine: Build and package Castle Game Engine programs.
.SS "Call with the current directory set to your project, like this:"
.IP
castle\-engine [OPTIONS]... COMMAND
.PP
Possible commands:
.PP
create\-manifest
.IP
Creates simple CastleEngineManifest.xml with guessed values.
.PP
compile
.IP
Compile project.
By default compiles for the current OS / current CPU (linux / x86_64).
You can use \fB\-\-os\fR / \fB\-\-cpu\fR options to compile to some other OS / CPU.
You can use \fB\-\-target\fR to compile for a collection of OS / CPU
combination (like "iOS" or "Android").
.PP
package
.IP
Package the application into the best archive format for given
operating system (OS) / processor (CPU) / target.
The OS, CPU and "target" can be changed just like at "compile".
.PP
install
.IP
Install the application created by previous "package" call.
Useful when OS is "android", it installs
the apk package created by previous "package" call
for Android. Useful for quick testing of your app on a device
connected through USB.
.PP
run
.IP
Run the application.
On some platforms, it requires installing the application first
(e.g. on Android, where we install and run on a device
connected through USB). So run the "install" command before.
On other platforms (e.g. standalone Windows, Linux, macOS...),
it simply runs the last compiled application.
So just "compile" the application first.
.PP
package\-source
.IP
Package the source code of the application.
.PP
clean
.IP
Clean leftover files from compilation and packaging.
Does not remove final packaging output.
.PP
simple\-compile
.IP
Compile the Object Pascal file (unit/program/library) given
as a parameter. This does not handle the Castle Game Engine projects
defined by CastleEngineManifest.xml files.
It merely calls "fpc" with proper command\-line options for
units/programs/libraries using our engine.
Use this instead of "compile" only if there's some good reason
you don't want to use CastleEngineManifest.xml to your project.
.PP
auto\-generate\-textures
.IP
Create GPU\-compressed versions of textures,
for the textures mentioned in <auto_compressed_textures>
inside the file data/material_properties.xml.
.PP
auto\-generate\-clean
.IP
Clear "auto_compressed" subdirectories, that should contain only
the output created by "auto\-generate\-textures" target.
.PP
generate\-program
.IP
Generate files to edit and run this project in Lazarus: lpr, lpi, castleautogenerated unit.
Depends on game_units being defined in the CastleEngineManifest.xml.
.PP
editor
.IP
Run Castle Game Engine Editor within this project, with possible
project\-specific components.
.PP
editor\-rebuild\-if\-needed
.IP
Internal. 1st part of "editor" command.
.PP
editor\-run [\-\-wait\-for\-process\-exit PROCESS\-ID]
.IP
Internal. 2nd part of "editor" command.
.PP
output
.IP
Output some project information (from the manifest).
Next parameter determines the information:
.IP
version
version\-code
.SS "Available options are:"
.TP
\fB\-h\fR / \fB\-\-help\fR
Print this help message and exit.
.TP
\fB\-v\fR / \fB\-\-version\fR
Print the version number and exit.
.TP
\fB\-V\fR / \fB\-\-verbose\fR
Verbose mode, output contains e.g. list of packaged
files.
.TP
\fB\-\-mode\fR=\fI\,debug\/\fR|release
Compilation mode, used by "compile" and "package"
commands. Also packaging mode on some platforms
(right now, Android). By default "release".
.TP
\fB\-\-assume\-compiled\fR
Do not automatically do "clean" and "compile"
before "package". Instead assume that compiled
executable for given OS/CPU/mode is already present
in the package directory.
.TP
\fB\-\-fast\fR
Do not "clean" before "package". Recompile only
what changed. This is faster for development, but
cannot guarantee that everything is recompiled in a
release mode.
.TP
\fB\-\-plugin\fR
Compile/package/install a browser NPAPI plugin.
DEPRECATED.
.TP
\fB\-\-fpc\-version\-iphone\-simulator\fR VERSION
When compiling for iPhone Simulator, we pass
\fB\-V\fR<VERSION> to the "fpc" command\-line. This is
necessary if you use the official "FPC for iOS"
package (see the "Getting Started \- iOS.rtf" inside
the "FPC for iOS" dmg for explanation). You can set
this to "auto" (this is the default) to auto\-detect
this based on regular FPC version. Or you can set
this to a particular version, like "3.0.5". Or you
can set this to empty "" to avoid passing any
\fB\-V\fR<VERSION> (suitable for FPC 3.1.1).
.TP
\fB\-\-compiler\-option\fR=\fI\,PARAM\/\fR
Extra parameter for "fpc" command line. For example
\fB\-\-compiler\-option\fR=\fI\,\-dUSE_MOUSE\/\fR will add \fB\-dUSE_MOUSE\fR.
You can use this parameter multiple times.
.TP
\fB\-\-output\fR=\fI\,DIR\/\fR
Where to place the output executables, packages,
and the "castle\-engine\-output" directory with
temporary generated files.
.TP
\fB\-\-project\fR=\fI\,DIR\/\fR
Where to search for the project
(CastleEngineManifest.xml file). By default we
search in the current directory. The argument can
either be a directory, or a filename of
CastleEngineManifest.xml file.
.TP
\fB\-\-package\-format\fR=\fI\,FORMAT\/\fR
Use with "package" command to customize the result.
Available FORMAT values:
.TP
\- default (platform specific; on most platforms
creates a zip/tar.gz archive; on Android creates
APK; on iOS creates Xcode project)
\- zip (pack all files into zip)
\- tar.gz (pack all files into tar.gz)
\- directory (put all files into a new subdirectory)
\- android\-apk (only on Android: create APK)
\- android\-app\-bundle (only on Android: create AAB)
\- ios\-archive\-ad\-hoc (only on iOS: archive using
"ad\-hoc" method to IPA file)
\- ios\-archive\-development (only on iOS: archive
using "development" method)
\- ios\-archive\-app\-store (only on iOS: distributes
the application to the TestFlight and the AppStore)
.TP
\fB\-\-package\-name\-no\-version\fR
Use with "package" command. The resulting
file/directory name will not contain the version
number.
.TP
\fB\-\-update\-only\-code\fR
Use with "package" command. Makes the packaging
faster, as you guarantee that only the Pascal code
have changed since last packaging (so you did not
change e.g. data/ or CastleEngineManifest.xml).
.TP
\fB\-\-ios\-simulator\fR
Use with "package" command when \fB\-\-target\fR=\fI\,iOS\/\fR.
Allows to run the project on iOS simulator.
.TP
\fB\-\-all\fR
Use with "auto\-generate\-clean" command. Indicates
to clean everything auto\-generated. By default we
only clean unused files from "auto_generated"
directories.
.TP
\fB\-\-manifest\-name\fR=\fI\,AlternativeManifest\/\fR.xml
Search and use given "AlternativeManifest.xml" file
instead of standard "CastleEngineManifest.xml".
Useful if you need to maintain completely different
project configurations for any reason.
.TP
\fB\-\-wait\-for\-process\-exit\fR=\fI\,PROCESS\-ID\/\fR
Internal, useful with "editor\-run".
.TP
\fB\-\-gui\-errors\fR
Show errors as GUI boxes. On Unix, requires
"zenity" installed.
.TP
\fB\-\-compiler\fR=\fI\,COMPILER\/\fR
Select compiler: "autodetect", "fpc", "delphi".
.TP
\fB\-\-target=\fR<target>
The target system for which we build/package.
Available <target> values:
.TP
\- "custom" (default): Build for a single OS and CPU
combination, determined by the \fB\-\-os\fR and \fB\-\-cpu\fR
options. These options, in turn, by default
indicate the current (host) OS/CPU.
.TP
\- "ios": Build for all the platforms necessary for
iOS applications. This includes both 32\-bit and
64\-bit iOS devices and iPhoneSimulator.
.TP
\- "android": Build for all the platforms necessary
for Android applications. This includes both 32\-bit
and 64\-bit Android devices.
.TP
\- "nintendo\-switch": Build an application for
Nintendo Switch.
.TP
\fB\-\-os=\fR<os>
Set the target operating system for which we
build/package.
This is ignored if you used \fB\-\-target=\fR<target>, with
<target> being something else than "custom".
Available <os> values:
.TP
linux
go32v2
win32
os2
freebsd
beos
netbsd
amiga
atari
solaris
qnx
netware
openbsd
wdosx
palmos
macosclassic (classic MacOS, that ended with
.TP
MacOS 9)
darwin (modern macOS 10.x, caled also Mac OS X)
emx
watcom
morphos
netwlibc
win64
wince
gba
nds
embedded
symbian
haiku
iphonesim
aix
java
android
nativent
msdos
wii
aros
dragonfly
win16
ios
.TP
\fB\-\-cpu=\fR<cpu>
Set the target processor for which we
build/package.
This is ignored if you used \fB\-\-target=\fR<target>, with
<target> being something else than "custom".
Available <cpu> values:
.TP
i386
m68k
powerpc
sparc
x86_64
arm
powerpc64
avr
armeb
mips
mipsel
jvm
i8086
aarch64 (64\-bit ARM)
sparc64
.PP
Full documentation on
https://castle\-engine.io/build_tool
.PP
castle\-engine version 7.0\-alpha.2.
Using Castle Game Engine ( https://castle\-engine.io/ ) version 7.0\-alpha.2.
Compiled with FPC 3.2.2.
Platform: Desktop, OS: Linux, CPU: x86_64 (this exe is using 64\-bit architecture).