Building a standalone app¶

nativella build turns a project into a single executable: a copy of the nativella command, PHP included, with the project packed inside. Run it, and the application starts: the machine needs no PHP.

cd path/to/notes
composer install --no-dev --optimize-autoloader
cd ..
nativella build notes

Packaging Notes 1.2.0 into dist/notes…
Done: dist/notes

nativella build [<project-dir>] [-o <output>]

The project directory defaults to the current one. The executable goes to dist/ in the current directory, named after the name of the application, in lower case with dashes (.exe on Windows); -o picks another path.

What ships¶

The whole project directory, vendor/ included, as a compressed archive, except:

The caches, logs and sessions of your machine stay behind, but the directories ship: the frameworks expect them to exist.

Symbolic links are followed, so the packages Composer links from path repositories ship as real files.

Preparing the project¶

• Install the dependencies without the development ones: composer install --no-dev --optimize-autoloader. Whatever is in vendor/ ships.
• Build the front-end assets, if you have any: node_modules stays behind, public/build does not.
• Set the production environment. With Symfony, composer dump-env prod writes .env.local.php, which ships (its name does not end with .local) and wins over the .env files.
• Avoid caches that hold absolute paths of your machine, like Laravel's config:cache: once extracted, the project runs from another directory.

Credentials¶

The users of the application can read whatever ships: the project is extracted in clear into their cache directory, and no packaging hides it. Where a credential comes from decides where it goes:

A release built by a CI can write the .env.local.php of composer dump-env prod from the secrets of the CI, just before nativella build: what it holds still ships, in clear. Keep it for what may be public.

At startup¶

The executable finds the project it carries and extracts it, once per build, into the cache directory of the user:

The next launches of the same build start right away. A new build extracts again, next to the previous one, and removes it once it runs: when no other instance of the application can be running from there. The data directory stays. Extraction is safe when two instances start at once: each one extracts aside, and the first to finish wins.

Then the application runs exactly as with nativella run. Its command line belongs to the application: a second launch forwards it to the running instance as AppReopened.

The data directory is separate from the extracted project: the database and the settings survive updates, as long as the identifier does not change.

What the machine needs¶

The executable carries the project and PHP: the machine needs neither PHP nor Composer. On Linux, it needs, to run, what the nativella command needs: the webview of the system, WebKitGTK 4.1, the library of the tray if the application shows a tray icon, and a glibc as recent as the one of the machine that built the nativella command, 2.35 for the releases, built on Ubuntu 22.04. The users of your application install them too: Installation lists the packages of each distribution, to repeat in the instructions of your application. On macOS, the executable needs nothing.

The PHP inside¶

The executable carries the PHP of the nativella command that built it: for the releases, PHP 8.5, linked statically, built with static-php-cli. The Symfony demo makes a 91 MB executable.

It has the extensions a Symfony, Laravel or Doctrine application needs (bcmath, ctype, curl, dom, fileinfo, filter, iconv, intl, mbstring, opcache, openssl, pdo_sqlite, phar, session, simplexml, sodium, sqlite3, tokenizer, xml, xmlreader, xmlwriter, zip, zlib), and no php.ini: PHP runs with its defaults, plus the settings Nativella sets (sessions in the cache directory of the application, the time zone of the system). intl carries ICU and its data, for every locale: 36 MB of the executable.

Android and iOS applications carry the same PHP, with the same extensions, built for the phone: see PHP for the phone.

Licenses¶

The executable contains the software of others, under their licenses: PHP, the libraries it is linked with (OpenSSL, curl, ICU, libxml2, GNU libiconv, libsodium, libzip, SQLite, zlib) and the ones php-src bundles (PCRE2, libmagic, lexbor, uriparser…), and the Rust crates of Nativella (Tauri, wry, tao, ext-php-rs…). Most of these licenses ask that their copyright notices and texts go with every copy, and the PHP License that it says "This product includes PHP software, freely available from http://www.php.net/software/".

The nativella command of the releases carries these third-party notices, gathered when it is built: nativella licenses prints them, and nativella build writes them next to the executable it builds.

Packaging Notes 1.2.0 into dist/notes…
Wrote the licenses of the software the application contains to dist/THIRD_PARTY_NOTICES.txt: distribute them with it.
Done: dist/notes

To distribute the application:

• ship THIRD_PARTY_NOTICES.txt with the executable, in the same archive or installer, or show it in the application, in an "about" page: App::thirdPartyNotices() returns it;
• add the licenses of what your project ships: the Composer packages of vendor/ (composer licenses lists them), the front-end libraries.

The libraries of the system the executable loads are not part of it, and need no notice: glibc, libstdc++ and WebKitGTK on Linux, the frameworks of macOS. The releases attach the notices of each platform too, THIRD_PARTY_NOTICES-<platform>.txt. A nativella built without them, by cargo build rather than castor nativella:build, says so, and nativella build warns.