basalt-core 0.0.0-rc5

package/dist/cli/desktop.d.ts

@@ -0,0 +1,339 @@
+/**
+ * `react-native run-linux`, `run-macos` and `run-windows`, which are one
+ * command with three names.
+ *
+ * Everything a desktop run does is the same on all three: find or build a host
+ * binary, work out the module name, make sure a packager is running, write a
+ * bundle, launch the host in the foreground and hand back its exit status. What
+ * differs is four strings -- the platform, the command name, the binary, and
+ * where its native sources are -- so that is what a platform package passes in.
+ *
+ * The same division as the C++ half, for the same reason. Three copies of this
+ * file would be three places for `--mode release` to mean something slightly
+ * different, and the first anyone would hear of it is an app that bundles
+ * without assets on one desktop.
+ *
+ * @format
+ */
+import type { PackagePlatform } from './packageApp';
+/**
+ * A target is the whole of what a platform package contributes.
+ *
+ *   platform     what Metro bundles for, and what Platform.OS will say
+ *   command      the CLI command name
+ *   binary       the host executable, with the extension the platform uses
+ *   nativeDir    that package's native/ directory, for --build
+ *   coreDir      basalt-core/native, where bootstrap.sh lives
+ *   toolchain    one sentence naming what --build needs installed
+ *   generator    optional CMake generator, when the default is wrong
+ */
+/**
+ * What a platform package contributes. The fields are documented above; this
+ * is the same list, so that a package leaving one out is a compile error
+ * rather than an undefined read a long way from here.
+ */
+export type Target = {
+    platform: PackagePlatform;
+    command: string;
+    binary: string;
+    nativeDir: string;
+    coreDir: string;
+    toolchain: string;
+    label?: string;
+    generator?: string;
+    /** Extra CMake arguments this platform always needs. */
+    configureArgs?: string[];
+};
+/** What React Native's CLI hands a command. Only the fields this file reads. */
+/**
+ * Where React Native's C++ is, and how to ask bootstrap for it. A checkout and
+ * an installed package are different layouts, and the difference is what
+ * bootstrap has to be told.
+ */
+export type ReactNativeSources = {
+    layout: 'checkout' | 'installed';
+    bootstrapArg: string;
+    rnDir: string;
+};
+/**
+ * CMake arguments, and the one-line notes the run prints to say why each is
+ * there -- "capability package, from ...". The notes exist so that a build
+ * picking something up from the app's dependencies says so rather than doing
+ * it silently.
+ */
+export type ContributedArgs = {
+    args: string[];
+    notes: string[];
+};
+export type CliContext = {
+    root: string;
+    reactNativePath: string;
+};
+/** The flags a run command accepts. */
+export type RunOptions = {
+    mode?: string;
+    build?: boolean;
+    packager?: boolean;
+    port?: number;
+    entryFile?: string;
+    /** `--module`: the name the app registered with AppRegistry. */
+    module?: string;
+    /** `--host-binary`: a host to run instead of the one that would be found. */
+    hostBinary?: string;
+    /** `--bundle`: where the bundle is, or should be written. */
+    bundle?: string;
+    /** `--jobs`: parallelism for the build. */
+    jobs?: number | string;
+    generator?: string;
+};
+export declare class MissingHost extends Error {
+}
+/**
+ * Executable, on a platform that has an opinion about it.
+ *
+ * `X_OK` is meaningless on Windows -- every readable file answers yes -- so the
+ * question there is only whether it is a file. Asking the same question of a
+ * Unix binary would call a non-executable one runnable, which is worse than
+ * either mistake this avoids.
+ */
+export declare function isExecutable(file: string): boolean;
+/**
+ * Where to look for the host, in order of how explicit the answer is.
+ *
+ * The last entry is the development checkout: when the platform package is
+ * being used from inside its own repository, the build tree is four
+ * directories up. That is what makes the demo app in examples/ work without
+ * configuration.
+ */
+export declare function candidates(projectRoot: string, options: RunOptions, target: Target): string[];
+export declare function resolveHost(projectRoot: string, options: RunOptions, target: Target): string;
+/**
+ * The React Native to build against, in either of the two shapes bootstrap
+ * accepts.
+ *
+ * A checkout, where bootstrap is handed the monorepo root and CMake the
+ * packages/react-native beneath it; or an installed package, where both are
+ * handed the package itself. The second is what every app has. React Native's
+ * npm package ships everything the host compiles against except
+ * ReactCxxPlatform, and bootstrap fetches that at the app's exact version --
+ * see docs/PORTING.md.
+ *
+ * This used to refuse an installed package outright, saying the npm package
+ * lacked the C++, long after bootstrap and CMake had learned to build from one.
+ * The command was the only part that had not.
+ */
+export declare function reactNativeSources(reactNativePath: string): ReactNativeSources;
+/**
+ * The optional native halves an app brings with it, as CMake definitions.
+ *
+ * Expo's runtime, worklets and Reanimated each compile from the app's own copy
+ * of the package (cmake/Expo.cmake and its siblings), and each is off unless
+ * named. `--build` never named them, so the host it built for an Expo app had
+ * no Expo runtime and the app failed at its first Expo import. Now whatever the
+ * app has installed is what gets built.
+ *
+ * expo-modules-core is looked for beside `expo` as well, since it is `expo`'s
+ * dependency rather than the app's, and a package manager that does not hoist
+ * leaves it there. Reanimated without worklets is skipped with a note rather
+ * than failing the configure: Reanimated 4 is built on worklets and
+ * Reanimated.cmake requires both.
+ */
+/**
+ * Capability packages: anything installed that declares native code of its own.
+ *
+ * A package says so in its own manifest -- `"basalt": {"native": "..."}` -- and
+ * the build reads that rather than this file knowing its name. Which is the
+ * difference between this and the three special cases below: Expo, worklets and
+ * Reanimated are third-party packages that will never carry the key, so they
+ * stay hardcoded; anything shipped for this platform does not have to be.
+ *
+ * Scanned from the app's own dependencies rather than the whole of
+ * node_modules: a transitive dependency contributing C++ to the host binary
+ * without the app asking is not a thing to make easy.
+ */
+export declare function capabilityPackages(projectRoot: string): string[];
+/**
+ * The app's own native modules: `<projectRoot>/modules/*` with a
+ * `native/CMakeLists.txt` in it.
+ *
+ * Expo's autolinking looks in exactly this directory for an app's local modules
+ * -- `expo-module.config.json` there is how `requireNativeModule('KinoProcess')`
+ * finds native code that was never published -- and an app that has written an
+ * iOS half and an Android half of one has nowhere to put the desktop half. A
+ * package would be the alternative, and publishing a package to yourself, so
+ * that one binary can compile a file already sitting in the repo, is not a
+ * reasonable thing to ask.
+ *
+ * **Presence is the declaration**, unlike a capability package, which says so in
+ * its manifest. A local module has no manifest to say it in: `create-expo-module
+ * --local` writes a config, an index and a platform directory, and no
+ * package.json. So the desktop half is declared the way the Apple half is --
+ * by being there -- and `native/CMakeLists.txt` is the name, because that is
+ * already what a host's package loop looks for.
+ *
+ * The rule capabilityPackages exists to keep is kept here for free: this is the
+ * app's own source tree, so nothing gets compiled into the binary that the app
+ * did not write.
+ */
+export declare function localNativeModules(projectRoot: string): string[];
+export declare function optionalNativeModules(projectRoot: string, platform: PackagePlatform): ContributedArgs;
+/**
+ * What the configure step has to name rather than leave to CMake's defaults.
+ *
+ * **The compiler.** React Native's C++ is built -Wall -Werror -Wpedantic and is
+ * warning-clean only under clang, which is why bootstrap's own configure line,
+ * CI and the README all name it. Left alone, CMake picks the system default --
+ * g++ on Ubuntu, cl on Windows -- and `--build` left it alone: a fresh Expo
+ * app's first build on Ubuntu 24.04 compiled Hermes (bootstrap names clang)
+ * and then stopped in ReactCommon on GCC's class-memaccess and pedantic
+ * __int128 errors. CC and CXX still win, as they would for a plain cmake.
+ *
+ * **On Windows, two more.** CMAKE_BUILD_TYPE, because unset MSVC picks the debug
+ * runtime and vcpkg follows it, while Hermes was built Release, and lld-link's
+ * complaint about _ITERATOR_DEBUG_LEVEL names neither. And vcpkg's toolchain
+ * file, found the way bootstrap.sh finds vcpkg: by a header it cannot do
+ * without, not by VCPKG_ROOT, which vcvars64.bat points at an empty copy.
+ */
+export declare function compilerArgs(platform: string, env?: NodeJS.ProcessEnv): string[];
+/**
+ * Git Bash, found rather than assumed.
+ *
+ * bootstrap.sh runs under Git Bash on Windows, and `bash` by name is not it on
+ * any machine with WSL: System32\bash.exe and WindowsApps\bash.exe both come
+ * first on PATH, and both launch Linux. Run there, bootstrap sees a Linux host
+ * and a Windows checkout and fails in ways that name neither.
+ *
+ * So: BASALT_BASH if set; else the bash.exe beside whichever git.exe is on PATH
+ * (Git for Windows puts git.exe in <Git>\cmd and bash.exe in <Git>\bin); else
+ * the standard install locations. Anything under System32 or WindowsApps is
+ * refused wherever it came from.
+ */
+export declare function findGitBash(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The environment `set` prints, as an object. Only lines of the form NAME=value;
+ * cmd prints nothing else there, but a banner from a profile script might.
+ */
+export declare function parseSetOutput(output: string): Record<string, string>;
+/**
+ * The MSVC environment, loaded the way a Developer Command Prompt loads it.
+ *
+ * clang-cl needs the Windows SDK's headers and libraries, and only
+ * vcvars64.bat puts them on INCLUDE and LIB; the Visual Studio CMake component
+ * it also puts on PATH brings cmake and ninja. Without this, `--build` worked
+ * only from a shell somebody had already prepared, and preparing one from
+ * PowerShell meant a wrapper script -- which is how an example app came to
+ * forward its arguments into npm's npx.ps1 with @args, and lose every one of
+ * them.
+ *
+ * Skipped when the shell already has it (VCToolsInstallDir is vcvars' own
+ * marker). VCPKG_ROOT is left as it was: vcvars points it at the copy bundled
+ * with Visual Studio, which has nothing installed in it.
+ */
+export declare function msvcEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * The React Native monorepo root, when `reactNativePath` is inside a checkout.
+ *
+ * `reactNativePath` is the package directory, two levels below the root in a
+ * checkout. An installed react-native has no monorepo above it, and this
+ * returns null for one; reactNativeSources above decides what to do then.
+ */
+export declare function monorepoRoot(reactNativePath: string): string | null;
+/**
+ * Building the host from an app.
+ *
+ * This is what `run-android` gets from Gradle and `run-ios` from Xcode. There
+ * is no equivalent to hand it to, so the work is here: vendor React Native's
+ * C++ dependencies, configure CMake against the app's own React Native, and
+ * build.
+ *
+ * Two things about where output goes. It goes under the app, in `.basalt`, not
+ * into `node_modules`, because npm rewrites node_modules on install and a
+ * Hermes build is not something to lose that way. And `third_party` is shared
+ * between builds of the same app rather than per configuration, because it
+ * depends on the React Native version and nothing else; the version stamp
+ * inside it is what keeps that honest.
+ *
+ * The first build is slow in a way `run-android` is not. It compiles Hermes and
+ * React Native's C++ core. Saying so before it starts is better than a silent
+ * half hour.
+ */
+/**
+ * A build failure, with what was in the build.
+ *
+ * A capability package -- or one of the app's own modules -- compiles into the
+ * same binary as the platform, so its compiler errors arrive looking exactly
+ * like the platform's own: a path, in a node_modules directory nobody was
+ * thinking about. Naming what contributed is the part that cannot be read off
+ * the error.
+ *
+ * Which package broke it is deliberately not claimed. The build output is
+ * streamed rather than captured, because a person watching a twenty-minute
+ * compile should see it happen, and buffering it to grep for a directory would
+ * trade that for a guess. Naming the contributors is what can be said honestly
+ * without giving that up.
+ */
+export declare function explainContributedFailure(projectRoot: string, error: Error): Error;
+/**
+ * Clears a build directory from before it was split by target.
+ *
+ * `.basalt/build` used to be the build directory itself; it is now a directory
+ * of them, one per target. The old one cannot become the new one: a CMake build
+ * directory records its own path, and moving it produces "The current
+ * CMakeCache.txt directory ... is different than the directory ..." -- which was
+ * this function's first shape, and it did not work.
+ *
+ * So it is moved aside rather than salvaged, and the target is built once more.
+ * That costs less than it sounds: the expensive vendoring -- Hermes, folly,
+ * ReactCxxPlatform -- lives in `.basalt/third_party`, which is untouched, and
+ * ccache carries most of the rest.
+ *
+ * Kept rather than deleted, because it is hundreds of megabytes of someone
+ * else's disk and the CLI is not the right thing to decide that. The line it
+ * prints says where it went.
+ */
+export declare function migrateBuildDirectory(workDir: string, log: (line: string) => void): void;
+export declare function buildHost(context: CliContext, options: RunOptions, target: Target): string;
+/**
+ * The name the app registered with AppRegistry.
+ *
+ * app.json's `name`, which is what `registerRootComponent` and every template
+ * use, and what run-android reads for the same purpose. Expo apps register
+ * "main" regardless, so an explicit --module has to win.
+ */
+export declare function resolveModuleName(projectRoot: string, options: RunOptions): string;
+/**
+ * Whether React Native's `start` command can load its Metro configuration in
+ * this app. Null when it can; otherwise the message to show.
+ *
+ * Development runs start Metro through that command, and its loader requires
+ * @react-native/metro-config from the app whatever the app's own
+ * metro.config.js says. A React Native template lists it. An Expo app does
+ * not -- Expo's CLI brings its own configuration -- so every Expo app's first
+ * development run died inside Metro with "Cannot resolve
+ * `@react-native/metro-config`", and only after the port timeout. Asked up
+ * front, the answer can name the version to install: the app's react-native
+ * version, which is what @react-native/community-cli-plugin pins it to.
+ */
+export declare function missingMetroConfig(projectRoot: string): string | null;
+/**
+ * The CLI command object React Native's CLI expects, for one target.
+ */
+export declare function makeRunCommand(target: Target): {
+    name: string;
+    description: string;
+    func: (argv: string[], context: CliContext, options: RunOptions) => Promise<void>;
+    options: ({
+        name: string;
+        description: string;
+        default: number;
+    } | {
+        name: string;
+        description: string;
+        default: string;
+    } | {
+        name: string;
+        description: string;
+        default?: undefined;
+    })[];
+};
+//# sourceMappingURL=desktop.d.ts.map

package/dist/cli/desktop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop.d.ts","sourceRoot":"","sources":["../../cli/desktop.ts"],"names":[],"mappings":"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"}