Skip to content

Commit

Permalink
Update README with detailed usage examples and demo link
Browse files Browse the repository at this point in the history
Expanded the README with additional usage examples for platform detection, app installations, and uninstallation processes. Clarified function names, added new functionality explanations, and included a link to a demo application.
  • Loading branch information
kdroidFilter committed Jan 10, 2025
1 parent 2eb6f54 commit b0128c8
Showing 1 changed file with 44 additions and 26 deletions.
70 changes: 44 additions & 26 deletions README.MD
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
## PlatformTools

**PlatformTools** is a Kotlin Multiplatform library designed to provide platform-specific utilities and tools for managing operating systems, application installation, and release fetching seamlessly across various platforms. The library is modular and divided into three main components: core, appmanager, and releasefetcher.

---
Expand Down Expand Up @@ -57,17 +59,17 @@ implementation("io.github.kdroidfilter:platformtools.releasefetcher:0.1.4")

The main goal of this library is to serve as a versatile toolkit for implementing platform-specific utilities. While this approach might seem contrary to the expect/actual pattern of Kotlin Multiplatform, PlatformTools fills a specific gap:

- It enables operating system detection within the JVM, which is not natively supported by KMP.
- It enables operating system detection for multiplatform environments such as JVM, WASM, or JS, where direct OS detection is not always straightforward.
- It allows OS detection in common code for minor functionalities where embedding such logic can be beneficial.

The core module provides tools for platform detection, including support for enums to represent different platforms:

```kotlin
import io.github.kdroidfilter.platformtools.Platform
import io.github.kdroidfilter.platformtools.getPlatform
import io.github.kdroidfilter.platformtools.getOperatingSystem

val platform = getPlatform()
println("Current platform: $platform")
val operatingSystem = getOperatingSystem()
println("Current operating system: $operatingSystem")
```

### AppManager (JVM and Android only)
Expand All @@ -79,26 +81,42 @@ The appmanager module provides an interface for managing application installatio
- **Linux**: DEB file
- **Mac**: PKG file

On Android, it is also possible to uninstall applications:

```kotlin
import io.github.kdroidfilter.platformtools.appmanager.getAppInstaller
import java.io.File

val appInstaller = getAppInstaller()

// Uninstall an app by package name
// Check if the app can request permission to install packages
val canRequest = appInstaller.canRequestInstallPackages()
println("Can request install packages permission: $canRequest")

// Request permission to install packages
appInstaller.requestInstallPackagesPermission()

// Install an application
val appFile = File("/path/to/app.apk")
appInstaller.installApp(appFile) { success, message ->
if (success) {
println("Installation successful")
} else {
println("Installation failed: $message")
}
}

// Uninstall an app by package name (Android only)
appInstaller.uninstallApp("com.example.app") { success, message ->
if (success) {
println("Uninstall started: $message")
println("Uninstallation started: $message")
} else {
println("Failed to uninstall: $message")
}
}

// Uninstall the current app
// Uninstall the current app (Android only)
appInstaller.uninstallApp { success, message ->
if (success) {
println("Uninstall started: $message")
println("Uninstallation started: $message")
} else {
println("Failed to uninstall: $message")
}
Expand All @@ -108,7 +126,7 @@ appInstaller.uninstallApp { success, message ->
On **Windows**, you can configure the installation of an app by setting `WindowsConfig.requireAdmin` to `true` or `false` depending on your needs. By default, this value is `true`. For example:

```kotlin
WindowsConfig.requireAdmin = false
WindowsConfig.requireAdmin = false
```

### ReleaseFetcher
Expand All @@ -132,12 +150,6 @@ val downloadLink = releaseFetcher.getDownloadLinkForPlatform(release!!)
println("Download link: $downloadLink")
```

#### How GitHub Release Fetcher Works

- **Latest Release Retrieval**: The `GitHubReleaseFetcher` fetches the latest release from the specified GitHub repository. It checks the tag name of the release to extract the version number.
- **Version Comparison**: The current application version is compared with the latest release version. If the latest version is greater, it signals that an update is available.
- **Platform-specific Asset Search**: Based on the platform (e.g., Android, Windows, Linux, Mac), it identifies assets in the release matching the appropriate file extension (e.g., `.apk` for Android, `.msi` for Windows) and retrieves the download link.

#### Downloader

The Downloader class provides functionality for downloading application files with progress tracking:
Expand Down Expand Up @@ -170,23 +182,23 @@ For Compose Desktop configuration under Windows, you can structure your settings

```kotlin
compose.desktop {
application {
mainClass = "com.kdroid.sample.MainKt"
nativeDistributions {
targetFormats(TargetFormat.Msi, TargetFormat.Deb, TargetFormat.Pkg)
windows {
perUserInstall = true
}
}
application {
mainClass = "com.kdroid.sample.MainKt"
nativeDistributions {
targetFormats(TargetFormat.Msi, TargetFormat.Deb, TargetFormat.Pkg)
windows {
perUserInstall = true
}
}
}
}
```

Setting `perUserInstall = true` avoids requiring admin rights during installation and enables background updates. **Note:** This feature is not feasible on Linux or Mac.

---

## 🛒 License
## 🛍️ License

PlatformTools is licensed under the [MIT License](https://opensource.org/licenses/MIT). Feel free to use, modify, and distribute the library under the terms of the license.

Expand All @@ -196,3 +208,9 @@ PlatformTools is licensed under the [MIT License](https://opensource.org/license

Contributions are welcome! If you want to improve this library, please feel free to submit a pull request or open an issue.

---

## 📢 Demo Application

A demo application with an integrated updater using this library is available [here](https://github.com/kdroidFilter/AppwithAutoUpdater).

0 comments on commit b0128c8

Please sign in to comment.