|
1 | | -   |
2 | | - |
3 | 1 | # AndroidBase |
4 | | -The `AndroidBase` project provides a Android app project template that includes the base modules/classes (ex: BaseActivity, BaseFragment, BaseViewModel ... etc.), setups for **Gradle Kotlin DSL** and eliminates boilerplate code. |
5 | | - |
6 | | -It helps you to create a well configured Android starter application with the most popular libraries (Ex: Android Architecuture Component, Retrofit/OkHttp, RxJava, Logging ... etc.). It creates and configures your project for you. Just start and focus on your rocket app development! |
7 | | - |
8 | | -> This project is suitable for those apps that fetch data from network and display data in list structure. |
9 | | -
|
10 | | -## Setup |
11 | | -1. Just click on [](https://github.com/enginebai/Base/generate) button to create a new repo starting from this template. Or you can clone this project by `git clone git@github.com:enginebai/Base.git` . |
12 | | -2. Change your project name in `settings.gradle.kts`. |
13 | | -3. Set your application ID in `Versions.kt` |
14 | | -4. Set the package name in `AndroidManifest.xml` file of `:app` module . |
15 | | -5. Select `com.enginebai.project` directory in "Project" tool window and rename package for your app. |
16 | | -6. Create your application class which extends `BaseApplication` in `:app` module, implement abstract methods and add to `AndroidManifest.xml` file. |
17 | | -7. Specify your retrofit base URL in `NetworkModule.kt` file. |
18 | | -8. Start to design your main layout xml file `fragment_main.xml` and fragment class. |
19 | | -9. Specify your `MainFragment.kt` name in navigation graph xml file. |
20 | | -9. That's all. Start your app development journey now 🎉. |
21 | | - |
22 | | -## Good Practices |
23 | | -* Add all dependencies versions in `Versions.kt` |
24 | | - |
25 | | -```kotlin |
26 | | -object Versions { |
27 | | - const val kotlin = "1.3.50" |
28 | | - const val awesomeLibrary = "x.y.z" |
29 | | - // TODO: add the library version |
30 | | - ... |
31 | | -} |
32 | | -``` |
33 | | -* Define all 3rd-party dependencies in `Dependencies.kt`, and use all versions definition in `Versions.kt`. |
34 | | - |
35 | | -```kotlin |
36 | | -object Dependencies { |
37 | | - const val rxJava = "io.reactivex.rxjava2:rxjava:${Versions.rxJava}" |
38 | | - // TODO: add standalone dependency here! |
39 | | - ... |
40 | | - |
41 | | - object Kotlin { |
42 | | - const val gradlePlugin = "org.jetbrains.kotlin:kotlin-gradle-plugin:${Versions.kotlin}" |
43 | | - const val stdLib = "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${Versions.kotlin}" |
44 | | - } |
45 | | - |
46 | | - // TODO: add inner object for sub-modules of library |
47 | | - object AndroidX { |
48 | | - ... |
49 | | - } |
50 | | - ... |
51 | | -} |
52 | | -``` |
53 | | - |
54 | | -* Always import dependency from `Dependencies.kt` in `build.gradle.kts` file. |
55 | | - |
56 | | -```kotlin |
57 | | -dependencies { |
58 | | - implementation(Dependencies.Glide.core) |
59 | | - "kapt"(Dependencies.Glide.compiler) |
60 | | - implementation(project(":base")) |
61 | | - // TODO: add by using dependency imported from `Dependencies.kt` file |
62 | | - ... |
63 | | -} |
64 | | -``` |
65 | | - |
66 | | -* Configure android build script in `Config.kt`. |
67 | | - |
68 | | -```kotlin |
69 | | -fun Project.configAndroid() = this.extensions.getByType<BaseExtension>().run { |
70 | | - compileSdkVersion(Versions.Android.sdk) |
71 | | - defaultConfig { |
72 | | - minSdkVersion(Versions.Android.minSdk) |
73 | | - targetSdkVersion(Versions.Android.sdk) |
74 | | - versionCode = Versions.App.versionCode |
75 | | - versionName = Versions.App.versionName |
76 | | - // TODO: add your configurations |
77 | | - ... |
78 | | - } |
79 | | - ... |
80 | | -} |
81 | | -``` |
82 | | - |
83 | | -It's equalivent to the old way `android { ... }` block in `build.gradle` file |
84 | | -```groovy |
85 | | -android { |
86 | | - compileSdkVersion 21 |
87 | | - buildToolsVersion "21.1.2" |
88 | | - defaultConfig { |
89 | | - applicationId "com.enginebai.moviehunt" |
90 | | - // TODO: add your configurations |
91 | | - ... |
92 | | - } |
93 | | - ... |
94 | | -} |
95 | | -``` |
96 | | - |
97 | | - |
98 | | -* Add all configuration variables inside `Config` object in `Config.kt`, and add `buildConfigField(...)` to include. |
99 | | - |
100 | | -```kotlin |
101 | | -object Config { |
102 | | - const val API_ROOT = "\"https://api.themoviedb.org/3/\"" |
103 | | - const val IMAGE_API_ROOT = "\"https://image.tmdb.org/t/p/\"" |
104 | | - // TODO: add your constants here, make sure to add extra double quotes for string value. |
105 | | -} |
106 | | - |
107 | | -fun Project.configAndroid() = this.extensions.getByType<BaseExtension>().run { |
108 | | - compileSdkVersion(Versions.Android.sdk) |
109 | | - defaultConfig { |
110 | | - ... |
111 | | - |
112 | | - buildConfigField("String", "API_ROOT", Config.API_ROOT) |
113 | | - buildConfigField("String", "IMAGE_API_KEY", Config.IMAGE_API_ROOT) |
114 | | - // TODO: add your varialbes here imported from `Config` object |
115 | | - ... |
116 | | - } |
117 | | - ... |
118 | | -} |
119 | | -``` |
120 | | - |
121 | | -* Add the common dependencies that share between modules to `Dependencies.kt` |
122 | | - |
123 | | -```kotlin |
124 | | -fun Project.importCommonDependencies() { |
125 | | - dependencies { |
126 | | - ... |
127 | | - implementation(Dependencies.material) |
128 | | - // TODO: add your common dependencies |
129 | | - .. |
130 | | - } |
131 | | -} |
132 | | -``` |
133 | | - |
134 | | -> **Note:** Remember to perform Gradle Sync to apply your changes when updating any files in `buildSrc`. |
135 | | -
|
136 | | -## Modules Structure |
137 | | -* `:base` module: It defines the base, common and utilities classes. |
138 | | -* `:app` module: That's your app module, just like a normal Android app project. You put all resources that app used, including strings, colors, dimensions, drawables. Or you can create a new modules (ex: `:common`) for that if you use multi-modules project. |
139 | | -* `/buildSrc`: It enables you to write the build script (`*.gradle.kts` files) in kotlin to manage dependencies and gets better IDE completion support. It gives you a way to develop build code more like regular code. More information please check [official document](https://docs.gradle.org/current/userguide/organizing_gradle_projects.html#sec:build_sources). |
140 | | - |
141 | | -> **Note**: Don't put the resources inside `:base` module since it can be updated from remote repo, please treat `:base` module as library. |
142 | | -
|
143 | | -## Included Libraries |
144 | | -* [Android Architecture Components](https://developer.android.com/topic/libraries/architecture), part of Android Jetpack for give to project a robust design, testable and maintainable. |
145 | | -* [Retrofit](https://github.com/square/retrofit) / [OkHttp](https://github.com/square/okhttp), Square open-source RESTful API and http client. |
146 | | -* [RxJava](https://github.com/ReactiveX/RxJava/) / [RxAndroid](https://github.com/ReactiveX/RxAndroid), reactive programming for JVM. |
147 | | -* [Koin](https://github.com/InsertKoinIO/koin), kotlin light-weight dependency injection. |
148 | | -* [Timber](https://github.com/JakeWharton/timber), for logging. |
149 | | -* [Epoxy](https://github.com/airbnb/epoxy), for RecyclerView complex view layout. |
150 | | - |
151 | | -## Useful Extensions |
152 | | -* See [Extension Functions.](./EXTENSIONS.md) |
153 | | - |
154 | | -## How to Update |
155 | | -Keep this repository as one of your project tracked remote. |
156 | | - |
157 | | -```shell |
158 | | -> git remote -v |
159 | | -> origin git@github.com:yourName/YourAwesomeProject.git (fetch) |
160 | | -> origin git@github.com:yourName/YourAwesomeProject.git (push) |
161 | | -> base git@github.com:enginebai/AndroidBase.git (fetch) |
162 | | -> base git@github.com:enginebai/AndroidBase.git (push) |
163 | | -``` |
164 | | - |
165 | | -And you can update by git pull or rebase from this remote repository. |
166 | | - |
167 | | -```shell |
168 | | -> git pull --rebase base master # pull and rebase |
169 | | -or |
170 | | -> get pull base master # pull and merge |
171 | | -``` |
172 | 2 |
|
173 | | -Resolve the conflicts and commit, this project will be one of your codebase module. |
| 3 | +There are three branches: |
| 4 | +* **library**: This is current branch for developing new feature, base or extension, then publish to JitPack via creating Git tag. |
| 5 | +* **template**: Major branch for Gradle Kotlin DSL template that can be used by other developers. |
| 6 | +* **gradle-kotlin-dsl**: Pure branch to demonstrate how to migrate from groovy to kotlin for gradle build system. Just like you create a whole new project from Android Studio, but in gradle kotlin DSL build file. |
174 | 7 |
|
175 | | -> **NOTE**: If you have own README, LICENSE files, feel free to accept your change while merging from base remote and resolving the conflicts. |
176 | 8 |
|
177 | 9 | ## LICENSE |
178 | 10 |
|
|
0 commit comments