115 lines
3.2 KiB
Markdown
115 lines
3.2 KiB
Markdown
# ShaarIt
|
|
|
|
**ShaarIt** is a native Android client for [Shaarli](https://github.com/shaarli/Shaarli), the self-hosted bookmark manager. Built with modern Android technologies, it provides a seamless mobile experience for managing your links.
|
|
|
|
## Features
|
|
|
|
* **Authentication**: Secure login to your self-hosted Shaarli instance (API v1).
|
|
* **Feed**: Infinite scroll browsing of your bookmarks with infinite loading.
|
|
* **Search & Filter**: Server-side search by terms and tag filtering.
|
|
* **Management**: Add new private/public links and delete existing ones.
|
|
* **Share Intent**: Quick-save links from other apps (browser, YouTube, etc.) via the Android Share menu.
|
|
|
|
## Tech Stack
|
|
|
|
* **Language**: Kotlin
|
|
* **UI**: Jetpack Compose (Material Design 3)
|
|
* **Architecture**: Clean Architecture + MVVM
|
|
* **Dependency Injection**: Dagger Hilt
|
|
* **Network**: Retrofit + Moshi + OkHttp
|
|
* **Concurrency**: Coroutines & Flow
|
|
* **Pagination**: Paging 3
|
|
|
|
## Prerequisites
|
|
|
|
Before building via the command line, ensure you have:
|
|
|
|
1. **JDK 17** (or newer) installed.
|
|
2. **Android SDK** installed.
|
|
3. **Gradle** (v8.0+) installed (only required if `gradlew` is missing).
|
|
* *Note for Windows users with Scoop:* `scoop install gradle`
|
|
|
|
## First Time Setup (If gradlew is missing)
|
|
|
|
If the `./gradlew` file is missing (e.g. fresh project generation), you need to generate it using a local Gradle installation:
|
|
|
|
```bash
|
|
gradle wrapper
|
|
```
|
|
|
|
This will create `gradlew`, `gradlew.bat` and the `gradle/wrapper` folder.
|
|
|
|
## Environment Setup (SDK)
|
|
|
|
Ensure you have the required Android SDK components installed (Platform API 34).
|
|
If you see a silent failure or "missing target" error, run:
|
|
|
|
```powershell
|
|
# Adjust path to your sdkmanager if needed
|
|
$SDK_MANAGER = "$env:ANDROID_HOME\cmdline-tools\latest\bin\sdkmanager"
|
|
& $SDK_MANAGER "platforms;android-34" "build-tools;34.0.0"
|
|
```
|
|
|
|
## Compilation Instructions (Command Line)
|
|
|
|
You can build the project without opening Android Studio by using the Gradle Wrapper included in the project.
|
|
|
|
### 1. Configure SDK Location
|
|
If your `ANDROID_HOME` environment variable is not set, create a `local.properties` file in the project root:
|
|
|
|
```bash
|
|
# Windows
|
|
echo sdk.dir=C:\\Users\\<Username>\\AppData\\Local\\Android\\Sdk > local.properties
|
|
|
|
# Linux/macOS
|
|
echo sdk.dir=/home/<username>/Android/Sdk > local.properties
|
|
```
|
|
|
|
### 2. Build the APK
|
|
|
|
Open your terminal in the project root folder.
|
|
|
|
**Windows (PowerShell/CMD):**
|
|
```powershell
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
**Linux/macOS:**
|
|
```bash
|
|
chmod +x gradlew
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
*The build process may take a few minutes as it downloads dependencies.*
|
|
|
|
### 3. Locate the APK
|
|
Once the build is successful, the APK file will be located at:
|
|
`app/build/outputs/apk/debug/app-debug.apk`
|
|
|
|
## Installation
|
|
|
|
To install the app on a connected device or emulator via command line:
|
|
|
|
```bash
|
|
# Ensure your device is connected and visible
|
|
adb devices
|
|
|
|
# Install the Debug APK
|
|
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
To run unit tests:
|
|
|
|
```bash
|
|
./gradlew test
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Open the **ShaarIt** app.
|
|
2. Enter your **Shaarli Instance URL** (e.g., `https://myserver.com/shaarli`).
|
|
3. Enter your **API Secret** (found in your Shaarli admin settings).
|
|
4. Click **Connect**.
|