Metadata-Version: 2.4
Name: duck-native
Version: 1.0.0
Summary: Build platform-specific native apps from Duck Framework web apps.
Author-email: Brian Musakwa <digreatbrian@gmail.com>
Maintainer-email: Brian Musakwa <digreatbrian@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Organization, https://github.com/duckframework
Project-URL: Homepage, https://duckframework.com
Project-URL: Contribution, https://duckframework.com/contribute
Project-URL: Blog, https://duckframework.com/blog
Project-URL: Documentation, https://docs.duckframework.com
Project-URL: Source, https://github.com/duckframework/duck-native
Project-URL: Issues, https://github.com/duckframework/duck-native/issues
Keywords: duck,duck framework,duck-native,python,native,native-apps,android,webview,cross-platform
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: duckframework>=2.3.1
Requires-Dist: click>=8.0
Requires-Dist: pillow>=10.0
Dynamic: license-file

<div align="center">

![Duck Native Wordmark](https://cdn.jsdelivr.net/gh/duckframework/duck-native@main/assets/images/duck-native-wordmark.svg)

**Turn your Duck Framework web app into a real Android app.**

[![PyPI version](https://img.shields.io/pypi/v/duck-native?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/duck-native/)
[![Python versions](https://img.shields.io/pypi/pyversions/duck-native?logo=python&logoColor=white)](https://pypi.org/project/duck-native/)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-green)](https://github.com/duckframework/duck-native/blob/main/LICENSE)
[![Status](https://img.shields.io/badge/status-beta-orange)](https://github.com/duckframework/duck-native)
[![Platform](https://img.shields.io/badge/platform-Android-3DDC84?logo=android&logoColor=white)](https://github.com/duckframework/duck-native)
[![GitHub stars](https://img.shields.io/github/stars/duckframework/duck-native?style=social)](https://github.com/duckframework/duck-native)

[Website](https://duckframework.com) · [Documentation](https://docs.duckframework.com) · [Native Actions](https://github.com/duckframework/duck-native/blob/main/readme/native-actions.md) · [Install Dependencies](https://github.com/duckframework/duck-native/blob/main/readme/dependencies-install-with-duck-toml.md) · [Termux Guide](https://github.com/duckframework/duck-native/blob/main/readme/termux-notes.md) · [Report a bug](https://github.com/duckframework/duck-native/issues)

</div>

---

## 📖 What is Duck Native?

You already have a web app built with [Duck Framework](https://duckframework.com).
Duck Native wraps it in an Android app, so people can install it from an APK or
the Play Store like any other app.

You do **not** need to write Kotlin or Java. You edit one Python file
(`native/config.py`) and run one command.

> 📚 **New here?** Read the guides:
> [📱 Native Actions](https://github.com/duckframework/duck-native/blob/main/readme/native-actions.md)
> (use the phone's features from your pages),
> [🧩 Native Widgets](https://github.com/duckframework/duck-native/blob/main/readme/native-widgets.md)
> (use real Android widgets from Python, like a date picker or bottom sheet),
> [📦 Installing Dependencies](https://github.com/duckframework/duck-native/blob/main/readme/dependencies-install-with-duck-toml.md)
> (set up Gradle and Kotlin with `duck sync`) and
> [🤖 Building on Termux](https://github.com/duckframework/duck-native/blob/main/readme/termux-notes.md)
> (build apps right on your phone).


## 📋 Table of contents

1. [What you need](#-what-you-need)
2. [Install and Setup](#-install-and-setup)
3. [Quick start](#-quick-start)
4. [Guides](#-guides)
5. [Commands](#-commands)
6. [Settings](#%EF%B8%8F-settings)
7. [Where is my app?](#-where-is-my-app)
8. [Troubleshooting](#-troubleshooting)
9. [Contributing](#-contributing)

## ✅ What you need

| Need | Why | Needed for `apk` command? |
| --- | --- | --- |
| Python 3.10 or newer | Runs Duck Native | Yes |
| A Duck Framework project | The app you want to wrap | Yes |
| JDK 17 | Runs Gradle | No |
| Android SDK | Builds the app | No |
| Gradle 8.9 or newer | Builds the app | No |

> 💡 Just want to try your app on a phone quickly? Skip the last three rows and
> use [`duck native apk`](#-get-a-ready-made-debug-apk).
>
> 📦 Need Gradle or Kotlin? Run `duck sync --with-dev`, see
> [Installing Dependencies](https://github.com/duckframework/duck-native/blob/main/readme/dependencies-install-with-duck-toml.md).
>
> 🤖 Developing on a phone? Follow the
> [Termux guide](https://github.com/duckframework/duck-native/blob/main/readme/termux-notes.md).

## 📦 Install and Setup

```bash
pip install duck-native
```

### Apply settings

You must enable native in your settings file:

```py
NATIVE_ENABLED = True
```

The above line enable Native capabilities for your app and it requires `duck-native` to be installed.

## 🚀 Quick start

Run these inside your Duck project folder.

**1. Create the config**

```bash
duck native init
```

This creates `native/config.py`.

**2. Edit it**

Open `native/config.py` and change at least these two lines:

```python
APP_NAME = "My Duck App"
PACKAGE_NAME = "com.yourname.myapp"
```

**3. Build**

```bash
duck native build
```

**4. Install the app**

Copy `build/app-debug.apk` to your phone and open it, or plug your phone in and
run `adb install -r build/app-debug.apk`.

That's it! 🎉

## 📚 Guides

| Guide | What you will learn |
| --- | --- |
| [📱 Native Actions](https://github.com/duckframework/duck-native/blob/main/readme/native-actions.md) | Show toasts, vibrate, copy text and share from your pages, and write your own Kotlin actions. |
| [📦 Installing Dependencies](https://github.com/duckframework/duck-native/blob/main/readme/dependencies-install-with-duck-toml.md) | Install Gradle, Kotlin and other system tools with one command, `duck sync`. |
| [🤖 Building on Termux](https://github.com/duckframework/duck-native/blob/main/readme/termux-notes.md) | Set up the SDK, Java and `aapt2` to build apps on an Android phone. |

## 🧰 Commands

> **`duck native` and `duck-native` are the same command.** We suggest
> `duck native` as the base command, and the examples here use it. Use
> `duck-native` if you prefer one word, or `python -m duck_native`.

| Command | What it does |
| --- | --- |
| `duck native init` | Creates `native/config.py` in your project. Add `--force` to overwrite. |
| `duck native check` | Checks your config and shows any problems. Builds nothing. |
| `duck native build` | Builds your app. Debug builds make an APK. |
| `duck native build --apk` | Builds a release APK instead of a bundle (when `DEBUG = False`). |
| `duck native apk` | Gets a ready-made debug APK, with no Gradle or SDK needed. |

Every command takes an optional project folder, for example
`duck native build ../my-app`.

### ⚡ Get a ready-made debug APK

```bash
duck native apk              # copies app-debug.apk into your build folder
duck native apk --install    # also installs it on a connected phone
duck native apk --output ~/Desktop/test.apk
```

This APK is the same for everyone, so settings like the app name, icon and
permissions are **not** applied. Use `duck native build` when you need them.

### 🔨 What `build` does

You will see each step in the terminal:

1. **Prepare**: copies the Android project into `build/android`.
2. **Generate**: creates your icons, splash screen and manifest.
3. **Build**: runs Gradle on the copy.
4. **Collect**: copies the finished APK or AAB into `build/`.

If the build fails, Duck Native prints suggestions based on the error.

## ⚙️ Settings

All settings live in `native/config.py`. The common ones:

| Setting | Example | What it does |
| --- | --- | --- |
| `APP_NAME` | `"My Duck App"` | Name shown under the app icon. |
| `PACKAGE_NAME` | `"com.yourname.myapp"` | Unique app ID. Pick it once and keep it. |
| `VERSION` | `"1.0.0"` | Version people see. |
| `VERSION_CODE` | `1` | Whole number. Raise it for every update. |
| `PERMISSIONS` | `["android.permission.INTERNET"]` | Only list what you need. |
| `ICON` | `"assets/icon.png"` | App icon. Use a square PNG. |
| `SPLASH_IMAGE` | `"assets/splash.png"` | Image shown while the app starts. |
| `ORIENTATION` | `"portrait"` | `portrait`, `landscape` or `unspecified`. |
| `FULLSCREEN` | `False` | Hide the status and navigation bars. |
| `DEBUG` | `True` | `True` builds a debug APK. `False` builds a release. |
| `COMPILE_SDK` | `36` | Lower this if the build can't load `android.jar`. |
| `SIGNING_KEYSTORE` | `"my.keystore"` | Needed to sign release builds. |

The generated file has a comment above every setting explaining it.

## 📁 Where is my app?

Everything ends up in the `build/` folder of your project:

```
build/
├── app-debug.apk      ← debug build
├── app-release.aab    ← release bundle (Play Store)
├── android/           ← working copy of the Android project
└── generated/         ← icons, splash and manifest made for you
```

## 🩹 Troubleshooting

| Problem | Fix |
| --- | --- |
| `Gradle was not found` | Install Gradle 8.9 or newer. |
| `SDK location not found` | Set the `ANDROID_HOME` environment variable to your SDK folder. |
| `failed to load include path ... android.jar` | Add `COMPILE_SDK = 34` to `native/config.py`. Common on Termux, see the [Termux guide](https://github.com/duckframework/duck-native/blob/main/readme/termux-notes.md). |
| `Failed to install the following Android SDK packages` | Run `sdkmanager --licenses` and accept everything. |
| `Pillow is required` | Run `pip install pillow`. |
| Release APK says `unsigned` | Set `SIGNING_KEYSTORE` and `SIGNING_KEY_ALIAS`, plus the `DUCK_KEYSTORE_PASSWORD` and `DUCK_KEY_PASSWORD` environment variables. |

Still stuck? [Open an issue](https://github.com/duckframework/duck-native/issues)
and paste the output of the failed command.

## 🤝 Contributing

Contributions are welcome! See the
[contribution guide](https://duckframework.com/contribute) or open an issue.

## 📄 License

Released under the [BSD 3-Clause License](https://github.com/duckframework/duck-native/blob/main/LICENSE).

