Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add (long overdue) explanation of "Package base files" concept #327

Merged
merged 1 commit into from
Oct 15, 2024
Merged

docs: add (long overdue) explanation of "Package base files" concept #327

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Welcome - and have a productive time using V and `vab`!
- [Tweaking defaults at compile time](#tweaking-defaults-at-compile-time)
- [Using `vab` from the command line](#using-vab-from-the-command-line)
- [Using `vab` programmatically](#using-vab-programmatically)
- [Package base files](#package-base-files)
- [Examples](#examples)
- [Compile V code to Android Compatible C code](#compile-v-code-to-android-compatible-c-code)
- [Compile C code to Android shared library (.so)](#compile-c-code-to-android-shared-library-so)
Expand Down Expand Up @@ -188,6 +189,36 @@ deploy_opt := android.DeployOptions{
}
android.deploy(deploy_opt) or { panic(err) }
```
# Package base files

"Package base files" are special directory structures usually found next to the executable
named `platforms/android`. Both `vab` itself and/or any *[extra commands](#extending-vab)*
can have a [`plaforms/android`]() directory in the root of the project the that contains
files that forms the basis of the APK/AAB package being built. The directories
mostly follow the same structure but often provides different entires such as:

* Custom `AndroidManifest.xml` tailored for the application.
* Custom Java sources for e.g. the "main" activity (under `platforms/android/src`).
* Custom resources like strings, and icons (under `platforms/android/res`).

**NOTE** Package base files can also be provided/tweaked by user application sources
via *their* `platforms/android` directory, or via the explicit `--package-overrides` flag,
which will copy all contents of `--package-overrides <path>` *on top of* the contents
provided as package base files. This allows for tweaking certain code bases instead
of reshipping everything.

Also note that directories named "`java`" in root of projects can act as *implicit*
`--package-overrides`... While this is not ideal, it has historically been a very useful
way for modules to provide tweaks to `vab`'s default package base files.

A similar approach (a special `jni` directory) is [being used](https://github.com/libsdl-org/SDL/tree/main/android-project/app/jni)
by the Android NDKs own tooling (`ndk-build`) for various reasons and can thus be
found in other projects where it serves similar inclusion purposes.
`vab` does not treat any `jni` directories specially.

See also [`fn prepare_package_base(opt PackageOptions) !PackageBase`](https://github.com/vlang/vab/blob/86d23cd703c0cfc2ce7df82535369a98d2f9d3b0/android/package.v#L940)
in `android/package.v` as well as [`--icon-mipmaps`](https://github.com/vlang/vab/blob/master/docs/FAQ.md#generating-mipmap-xxxhdpi-icons-in-the-apkaab) in
the [FAQ.md](https://github.com/vlang/vab/blob/master/docs/FAQ.md).

# Examples

Expand Down