HighCapable/SweetProperty
5
0
Fork 0
mirror of https://github.com/HighCapable/SweetProperty.git synced 2025-09-05 10:15:36 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
fankesyooni
2023-09-03 01:11:31 +08:00
commit f03805ff2c
53 changed files with 4392 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
docs/guide.md Normal file
View File

@@ -0,0 +1,297 @@
# Sweet Property Documentation
Before you start using it, it is recommended that you read this document carefully so that you can better understand how it works and its functions.
If your project is still managed using Groovy DSL, it is recommended to migrate to Kotlin DSL.
We will no longer be responsible for troubleshooting and fixing any issues that occur with this plugin in Groovy DSL,
and Groovy DSL support may be dropped entirely in later releases.
Note: Usage in the Groovy DSL will not be detailed in this document.
## Prerequisites
Please note that `SweetProperty` is recommended to be loaded using the new `pluginManagement` method, which is a feature added since Gradle `7.x.x`
version.
If your project is still managed using the `buildscript` method, it is recommended to migrate to the new method, and the instructions for using the
old version will no longer be provided here.
## Quick Start
First, open `settings.gradle.kts` in your root project.
Add the following code to `settings.gradle.kts` in your root project.
If `pluginManagement` already exists, there is no need to add it again.
> The following example
```kotlin
pluginManagement {
repositories {
gradlePluginPortal()
google()
mavenCentral()
}
}
plugins {
id("com.highcapable.sweetproperty") version "<version>"
}
```
Please replace `<version>` in the above code with the latest version in
[Release](https://github.com/HighCapable/SweetProperty/releases), please note <u>**DO NOT**</u> add `apply false` after.
After the above configuration is completed, run Gradle Sync once.
## Function Configuration
You can configure `SweetProperty` to achieve custom and personalized functions.
`SweetProperty` provides you with a relatively rich set of customizable functions.
The following are the descriptions and configuration methods of these functions.
Please add `sweetProperty` method block to your `settings.gradle.kts` to start configuring `SweetProperty`.
> The following example
```kotlin
sweetProperty {
// Enable SweetProperty, set to false will disable all functions
isEnable = true
// Global configuration
// You can modify the configuration in all projects in the global configuration
// Configurations that are not declared in each project will use the global configuration
// The functions in each configuration method block are exactly the same
// You can refer to the configuration method of the root project and sub-projects below
global {
// General code generation function
// Here you can configure the related functions of the build script and the project generated code at the same time
all {
// Enable functionality
// You can set "sourcesCode" and "buildScript" respectively
isEnable = true
// Set properties name
// In general, you don't need to modify this setting, the wrong file name will lead to getting empty key-values content
// If you have a properties file with a custom name, you can modify the settings here
// Note: It is recommended to configure each project individually, rather than modifying globally, in case of problems
propertiesFileName = "gradle.properties"
// Whether to enable the exclusion of non-string type key-values content
// Enabled by default, when enabled, key-values and content that are not string types will be excluded from the properties key-values
// This can exclude e.g. configuration of some system environment variables or data in memory
isEnableExcludeNonStringValue = true
// Whether to enable the type automatic conversion function
// Enabled by default, when enabled,
// the type in the properties key-values will be automatically recognized and converted to the corresponding type
// For example "name=hello" and "number=1" they will be automatically converted to String and Int
isEnableTypeAutoConversion = true
// Whether to enable key-values content interpolation
// Enabled by default, after enabling, the ${...} content in the properties key-values content
// will be automatically recognized and replaced
// Note: The interpolated content will only be searching from the current (current configuration file) properties key-values list
isEnableValueInterpolation = true
// Set a fixed attribute key-value array
// Here you can set some key values that must exist,
// and these key values will be generated regardless of whether they can be obtained from the properties key-values
// These key-values use the content of the properties key-values when the properties key-values exists,
// and use the content set here when it does not exist
// Note: There cannot be special symbols and spaces in the attribute key value name, otherwise the generation may fail
// For example: you need to obtain the key or certificate stored on your own devices,
// but these keys are not available on other people's devices
// At this point this function will become very useful, you can set the default value when there are no these key-values
// Of course, you can also use this function to forcefully add additional properties key-values to the generated code
permanentKeyValues(
"permanent.some.key1" to "some_value_1",
"permanent.some.key2" to "some_value_2"
)
// Set an array of properties key-values names that need to be excluded
// Here you can set some key names that you want to exclude from the known properties keys
// These keys are excluded when they exist in the properties keys and will not appear in the generated code
// Note: If you exclude the key-values set in "permanentKeyValues",
// then they will only become the initial key-values content you set and continue to exist
// You can pass in a Regex or use String.toRegex to use the regex function
excludeKeys(
"exclude.some.key1",
"exclude.some.key2"
)
// Set where to generate properties key-values
// Defaults to "CURRENT_PROJECT" and "ROOT_PROJECT"
// You can use the following types to set
// "CURRENT_PROJECT" ← Current project
// "ROOT_PROJECT" ← Root project
// "GLOBAL" ← Global (user directory)
// "SYSTEM" ← System
// "SYSTEM_ENV" ← System environment variable
// SweetProperty will generate properties key-values sequentially from the generation positions you set,
// and the order of generation positions is determined by the order you set
// Pay Attention: "GLOBAL", "SYSTEM", "SYSTEM_ENV" may have keys and certificates, please manage the generated code carefully
generateFrom(CURRENT_PROJECT, ROOT_PROJECT)
}
// Project generation code function
// This function is similar to the BuildConfig automatically generated by Android projects
// The code generated in the project can be directly used by the current project
// The configuration here includes the configuration in "all", you can override it
sourcesCode {
// Custom generated directory path
// You can fill in the path relative to the current project
// Defaults to "build/generated/sweet-property"
// It is recommended to place the generated code in the "build" directory,
// because the generated code is not recommended to be modified
generateDirPath = "build/generated/sweet-property"
// Custom generated package name
// Android projects use the "namespace" in the "android" configuration method block by default
// Ordinary Kotlin on Jvm projects use the "project.group" of the project settings by default
// You don’t need to set it, the package name will automatically match under normal circumstances
packageName = "com.example.mydemo"
// Custom generated class name
// By default, the name of the current project + "Properties" is used
// You don't need to set it, the class name will be automatically matched under normal circumstances
className = "MyDemo"
// Whether to enable restricted access
// Not enabled by default
// When enabled, the "internal" modifier will be added to the generated classes and methods
// If your project is a tool library or dependency, it is usually recommended to enable it
// Once enabled, it can prevent other developers from calling your project properties key-values when referencing your library
isEnableRestrictedAccess = false
}
// Build script generate code function
// The code generated in the build script can be directly used by the current "build.gradle.kts"
// The configuration here includes the configuration in "all", you can override it
// Note: There is also a "buildscript" method block in Gradle, but it is just a lowercase "s", please don't confuse it
buildScript {
// Custom build script extension method name
// Defaults to "property"
// You will call it in "build.gradle.kts" using something like "property.some.key"
extensionName = "property"
}
}
// Root project configuration
// This is a special configuration method block that can only be used in root projects
rootProject {
all {
// Configure "all"
}
sourcesCode {
// Configure "sourcesCode"
}
buildScript {
// Configure "buildScript"
}
}
// Sub-projects configuration
// Fill in the full name of the project that needs to be configured in the method parameters to configure the corresponding project
// If your project is a nested sub-projects, such as app → sub
// At this point you need to use ":" to separate multiple sub-projects, such as "app:sub"
// You don't need to fill in the ":" in front of the sub-projects, such as ":app"
// The name of the root project cannot be used directly to configure sub-projects, please use "rootProject"
project("app") {
all {
// Configure "all"
}
sourcesCode {
// Configure "sourcesCode"
}
buildScript {
// Configure "buildScript"
}
}
}
```
If you want to use it in Groovy DSL, please change the `=` of all variables to spaces, delete the `is` in front of `Enable` and lowercase `E`.
If you encounter `Gradle DSL method not found` error, the solution is to migrate to Kotlin DSL.
If you don't want to use the Kotlin DSL entirely, you can also migrate just `settings.gradle` to `settings.gradle.kts`.
## Usage Example
Below is a project's `gradle.properties` configuration file.
```properties
project.groupName=com.highcapable.sweetpropertydemo
project.description=Hello SweetProperty Demo!
project.version=1.0.0
```
In the build script `build.gradle.kts`, we can use these keys directly as shown below.
Here is an example of the configuration part published by Maven.
```kotlin
publications {
create<MavenPublication>("maven") {
groupId = property.project.groupName
version = property.project.version
pom.description.set(property.project.description)
from(components["java"])
}
}
```
Similarly, you can also call the generated key-value in the current project.
```kotlin
SweetPropertyDemoProperties.PROJECT_GROUP_NAME
SweetPropertyDemoProperties.PROJECT_DESCRIPTION
SweetPropertyDemoProperties.PROJECT_VERSION
```
Let's take the Android project as an example.
In Android projects, it is usually necessary to configure many repeated and fixed properties, such as `targetSdk`.
```properties
project.compileSdk=33
project.targetSdk=33
project.minSdk=22
```
When you set the `isEnableTypeAutoConversion = true`, `SweetProperty` will try to convert it to the corresponding type under the
default configuration during the process of generating the entity class.
For example, the type of the key-value used below can be recognized as an integer and can be directly used by the project configuration.
```kotlin
android {
compileSdk = property.project.compileSdk
defaultConfig {
minSdk = property.project.minSdk
targetSdk = property.project.targetSdk
}
}
```
You no longer need to use `buildConfigField` to add code to `BuildConfig`,
with the properties key-values code generated by `SweetProperty`, you can manage your project more flexibly.
You can also use `${...}` in properties values to refer to each other, but recursive references are not allowed.
When you set the `isEnableValueInterpolation = true`,
`SweetProperty` will automatically merge the contents of these references into the corresponding locations.
```properties
project.name=MyDemo
project.developer.name=myname
project.url=https://github.com/${project.developer.name}/${project.name}
```
Note: This feature is provided by `SweetProperty`, and the native `gradle.properties` does not support this feature.
**Possible Problems**
If your project only has one root project and does not import any sub-projects,
if extension methods are not generated properly,
you can solve this problem by migrating your root project to a sub-projects and importing this sub-projects in `settings.gradle.kts`.
We generally recommend classifying the functions of the project, and the root project is only used to manage plugins and some configurations.
**Limitations Note**
`SweetProperty` cannot generated extension methods in `settings.gradle.kts`, because this belongs to the upstream of `SweetProperty`.
## Feedback
If you encounter any problems while using `SweetProperty`, you can always open an `issues` on GitHub to give us feedback.