Changelog
The version update history of
Gropifyis recorded here.
Pay Attention
We will only maintain the latest API version. If you are using an outdated API version, you voluntarily renounce any possibility of maintenance.
Notice
To avoid translation time consumption, Changelog will use Google Translation from Chinese to English, please refer to the original text for actual reference.
Time zone of version release date: UTC+8
- Fixed the issue where
permanentKeyValueswas incorrectly configured toreplacementKeyValues - Optimized the automatic type conversion function for property key-values, fixed the problem of negative long integers being converted to integers
- Optimized log output function, added tags and text colors for each type of log
- Added
keyValueRulesto manually specify the type of property key-values, effective whenuseTypeAutoConversionis enabled - Enhanced debugging function, added detailed log output in debug mode
- Fixed the issue where
extensionNamewas judged as empty and illegal under default settings - Added judgment content for default extension method names that may cause conflicts
- Added
manifestPlaceholdersproperty key-value synchronization function toandroidconfiguration method block - Fixed the problem of Javapoet and Kotlinpoet processing special escape characters in source code generation
- Fixed other issues that may cause build script compilation failure
- 修复
permanentKeyValues被错误地配置到replacementKeyValues的问题 - 优化属性键值的类型自动转换功能，修复负数长整型被转换为整型的问题
- 优化日志输出功能，加入每种日志的标签和文字颜色
- 新增
keyValueRules可手动指定属性键值的类型，在启用了useTypeAutoConversion时生效 - 增强调试功能，加入了调试模式下的详细日志输出
- 修复
extensionName在默认设置情况下被判断为空格式非法的问题 - 增加了可能造成冲突的默认扩展方法名称判断内容
android配置方法块新增manifestPlaceholders属性键值同步功能- 修复源代码生成 Javapoet 和 Kotlinpoet 处理特殊转义字符的问题
- 修复其它可能导致构建脚本编译失败的问题
Looking Toward the Future
The future is bright and uncertain, let us look forward to the future development potential of
Gropify.
Future Plans
Features that
Gropifymay add later are included here.
Support More Project Types
Gropify currently supports generating properties into the source code of Kotlin, Java, and Android projects. In the future, it may support more projects that can participate in Gradle builds, such as C/C++ (Android JNI), Swift, etc., to meet the needs of more developers.
展望未来
未来是美好的，也是不确定的，让我们共同期待
Gropify在未来的发展空间。
未来的计划
这里收录了
Gropify可能会在后期添加的功能。
支持更多项目类型
Gropify 目前支持将属性生成到 Kotlin、Java 和 Android 项目的源代码中，在未来可能会支持更多能够参与 Gradle 构建的项目，例如 C/C++ (Android JNI)、Swift 等，以满足更多开发者的需求。
The configuration plan format of Gropify is similar to SweetProperty. If you are using SweetProperty, you can consider migrating to Gropify.
Usage
Gropify is mainly designed for Kotlin DSL build scripts. Groovy can directly use properties from the gradle.properties file as variables, but you can still use Gropify to achieve type-safe property access.
Gropify also supports generating properties (similar to those defined in a gradle.properties file) in a type-safe way into the source code of Kotlin, Java, and Android projects for use at application runtime—similar to Android's BuildConfig's buildConfigField feature.
Suppose we have the following gradle.properties file.
The following example
project.app.name=Gropify-Demo
+project.app.version=1.0.0
+Here is an example of calling the code automatically generated by Gropify.
Build Script (Kotlin DSL, Groovy DSL)
val appName = gropify.project.app.name
+val appVersion = gropify.project.app.version
+def appName = gropify.project.app.name
+def appVersion = gropify.project.app.version
+Source Code (Kotlin, Java)
val appName = MyAppProperties.PROJECT_APP_NAME
+val appVersion = MyAppProperties.PROJECT_APP_VERSION
+var appName = MyAppProperties.PROJECT_APP_NAME;
+var appVersion = MyAppProperties.PROJECT_APP_VERSION;
+Gropify also supports Kotlin Multiplatform projects, and you can use the generated property classes in the commonMain source set.
Language Requirement
It's recommended to use Kotlin DSL to configure your project's build scripts. Groovy is also supported, but in pure Groovy projects some configuration syntax may have compatibility issues.
In Groovy DSL, we will no longer be responsible for troubleshooting and fixing any issues that arise from using this plugin, and it may be completely unsupported in future versions.
Contribution
The maintenance of this project is inseparable from the support and contributions of all developers.
This project is currently in its early stages, and there may still be some problems or lack of functions you need.
`,21),v={href:"https://github.com/HighCapable/Gropify/issues",target:"_blank",rel:"noopener noreferrer"};function _(k,A){const o=r("ExternalLinkIcon");return i(),l("div",null,[c,d,u,y,e("p",null,[s("The project icon was designed by "),e("a",h,[s("MaiTungTM"),a(o)]),s(". The name comes from "),m,s("radleP"),g,s(", meaning a plugin for Gradle properties.")]),e("p",null,[s("It is a brand-new project rebuilt from "),e("a",b,[s("SweetProperty"),a(o)]),s(", borrowing previous design ideas and making it more polished and easier to use.")]),f,e("p",null,[s("If possible, feel free to submit a PR to contribute features you think are needed to this project or go to "),e("a",v,[s("GitHub Issues"),a(o)]),s(" to make suggestions to us.")])])}const D=n(t,[["render",_],["__file","home.html.vue"]]);export{D as default}; diff --git a/assets/home.html-9eiAlurd.js b/assets/home.html-9eiAlurd.js new file mode 100644 index 0000000..6dbd892 --- /dev/null +++ b/assets/home.html-9eiAlurd.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-6a609e09","path":"/zh-cn/guide/home.html","title":"介绍","lang":"zh-CN","frontmatter":{},"headers":[{"level":2,"title":"背景","slug":"背景","link":"#背景","children":[]},{"level":2,"title":"用途","slug":"用途","link":"#用途","children":[]},{"level":2,"title":"语言要求","slug":"语言要求","link":"#语言要求","children":[]},{"level":2,"title":"功能贡献","slug":"功能贡献","link":"#功能贡献","children":[]}],"git":{"updatedTime":1762849016000,"contributors":[{"name":"fankesyooni","email":"qzmmcn@163.com","commits":1}]},"filePathRelative":"zh-cn/guide/home.md"}');export{e as data}; diff --git a/assets/home.html-TFY4cEol.js b/assets/home.html-TFY4cEol.js new file mode 100644 index 0000000..46f19df --- /dev/null +++ b/assets/home.html-TFY4cEol.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-efb45d4c","path":"/en/guide/home.html","title":"Introduction","lang":"en-US","frontmatter":{},"headers":[{"level":2,"title":"Background","slug":"background","link":"#background","children":[]},{"level":2,"title":"Usage","slug":"usage","link":"#usage","children":[]},{"level":2,"title":"Language Requirement","slug":"language-requirement","link":"#language-requirement","children":[]},{"level":2,"title":"Contribution","slug":"contribution","link":"#contribution","children":[]}],"git":{"updatedTime":1762849016000,"contributors":[{"name":"fankesyooni","email":"qzmmcn@163.com","commits":1}]},"filePathRelative":"en/guide/home.md"}');export{e as data}; diff --git a/assets/home.html-no62ZQLF.js b/assets/home.html-no62ZQLF.js new file mode 100644 index 0000000..d3692b6 --- /dev/null +++ b/assets/home.html-no62ZQLF.js @@ -0,0 +1,11 @@ +import{_ as n,r as l,o as p,c as r,a as e,b as s,d as o,e as i}from"./app-aH6YcK-Q.js";const c={},t=e("h1",{id:"介绍",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#介绍","aria-hidden":"true"},"#"),s(" 介绍")],-1),d=e("blockquote",null,[e("p",null,[e("code",null,"Gropify"),s(" 是一个类型安全且现代化的 Gradle 属性插件。")])],-1),y=e("h2",{id:"背景",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#背景","aria-hidden":"true"},"#"),s(" 背景")],-1),u=e("p",null,[s("这是一个为 Gradle 构建脚本设计的插件，旨在将类似 "),e("code",null,"gradle.properties"),s(" 文件中的属性以类型安全的方式引入到构建脚本中，从而避免硬编码字符串可能带来的问题。")],-1),h={href:"https://github.com/Lagrio",target:"_blank",rel:"noopener noreferrer"},v=e("strong",null,"G",-1),m=e("strong",null,"ropify",-1),b={href:"https://github.com/HighCapable/SweetProperty",target:"_blank",rel:"noopener noreferrer"},_=i(`Gropify 的配置方案与 SweetProperty 类似，如果你正在使用 SweetProperty，你可以考虑将其迁移到 Gropify。
用途
Gropify 主要针对 Kotlin DSL 构建脚本设计，Groovy 语言可以直接将 gradle.properties 文件中的属性作为变量使用，但是你也可以通过 Gropify 来实现类型安全的属性访问。
Gropify 同时支持将类似 gradle.properties 文件中的属性以类型安全的方式生成到 Kotlin、Java、Android 项目的源码中以供应用程序运行时使用，功能类似 Android 的 BuildConfig 中的 buildConfigField 功能。
假设我们有以下 gradle.properties 文件。
示例如下
project.app.name=Gropify-Demo
+project.app.version=1.0.0
+这是 Gropify 自动生成的代码调用示例。
构建脚本 (Kotlin DSL、Groovy DSL)
val appName = gropify.project.app.name
+val appVersion = gropify.project.app.version
+def appName = gropify.project.app.name
+def appVersion = gropify.project.app.version
+源代码 (Kotlin、Java)
val appName = MyAppProperties.PROJECT_APP_NAME
+val appVersion = MyAppProperties.PROJECT_APP_VERSION
+var appName = MyAppProperties.PROJECT_APP_NAME;
+var appVersion = MyAppProperties.PROJECT_APP_VERSION;
+Gropify 同样支持 Kotlin Multiplatform 项目，你可以在 commonMain 源集中使用生成的属性类。
语言要求
推荐使用 Kotlin DSL 来配置项目的构建脚本，Groovy 语言同样受支持，但在纯 Groovy 项目中部分配置语法可能存在兼容性问题。
在 Groovy DSL 中使用此插件发生的任何问题，我们都将不再负责排查和修复，并且在后期版本可能会完全不再支持 Groovy DSL。
功能贡献
`,19),g={href:"https://github.com/HighCapable/Gropify/issues",target:"_blank",rel:"noopener noreferrer"};function A(F,f){const a=l("ExternalLinkIcon");return p(),r("div",null,[t,d,y,u,e("p",null,[s("项目图标由 "),e("a",h,[s("MaiTungTM"),o(a)]),s(" 设计，名称取自 "),v,s("radleP"),m,s("，意为针对 Gradle 属性的插件。")]),e("p",null,[s("它是基于 "),e("a",b,[s("SweetProperty"),o(a)]),s(" 重构的全新项目，借鉴了以往的设计方案，使得其在原有基础上更加完善和易用。")]),_,e("p",null,[s("本项目的维护离不开各位开发者的支持和贡献，目前这个项目处于初期阶段，可能依然存在一些问题或者缺少你需要的功能， 如果可能，欢迎提交 PR 为此项目贡献你认为需要的功能或前往 "),e("a",g,[s("GitHub Issues"),o(a)]),s(" 向我们提出建议。")])])}const k=n(c,[["render",A],["__file","home.html.vue"]]);export{k as default}; diff --git a/assets/index.html-7DNoxpGZ.js b/assets/index.html-7DNoxpGZ.js new file mode 100644 index 0000000..8b4fd3c --- /dev/null +++ b/assets/index.html-7DNoxpGZ.js @@ -0,0 +1 @@ +import{_ as e,o as c,c as t}from"./app-aH6YcK-Q.js";const n={};function _(o,r){return c(),t("div")}const a=e(n,[["render",_],["__file","index.html.vue"]]);export{a as default}; diff --git a/assets/index.html-7LpniZrm.js b/assets/index.html-7LpniZrm.js new file mode 100644 index 0000000..9c52c22 --- /dev/null +++ b/assets/index.html-7LpniZrm.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-c0c85b84","path":"/zh-cn/","title":"首页","lang":"zh-CN","frontmatter":{"home":true,"title":"首页","heroImage":"/images/logo.svg","actions":[{"text":"快速上手","link":"/zh-cn/guide/home","type":"primary"},{"text":"更新日志","link":"/zh-cn/about/changelog","type":"secondary"}],"footer":"Apache-2.0 License | Copyright (C) 2019 HighCapable"},"headers":[],"git":{"updatedTime":1762849016000,"contributors":[{"name":"fankesyooni","email":"qzmmcn@163.com","commits":1}]},"filePathRelative":"zh-cn/index.md"}');export{e as data}; diff --git a/assets/index.html-H28pjygm.js b/assets/index.html-H28pjygm.js new file mode 100644 index 0000000..8b4fd3c --- /dev/null +++ b/assets/index.html-H28pjygm.js @@ -0,0 +1 @@ +import{_ as e,o as c,c as t}from"./app-aH6YcK-Q.js";const n={};function _(o,r){return c(),t("div")}const a=e(n,[["render",_],["__file","index.html.vue"]]);export{a as default}; diff --git a/assets/index.html-J5Mpt7Vl.js b/assets/index.html-J5Mpt7Vl.js new file mode 100644 index 0000000..e2802a0 --- /dev/null +++ b/assets/index.html-J5Mpt7Vl.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-2d0a870d","path":"/en/","title":"Home","lang":"en-US","frontmatter":{"home":true,"title":"Home","heroImage":"/images/logo.svg","actions":[{"text":"Get Started","link":"/en/guide/home","type":"primary"},{"text":"Changelog","link":"/en/about/changelog","type":"secondary"}],"footer":"Apache-2.0 License | Copyright (C) 2019 HighCapable"},"headers":[],"git":{"updatedTime":1762849016000,"contributors":[{"name":"fankesyooni","email":"qzmmcn@163.com","commits":1}]},"filePathRelative":"en/index.md"}');export{e as data}; diff --git a/assets/index.html-WpXt5Cz7.js b/assets/index.html-WpXt5Cz7.js new file mode 100644 index 0000000..8b4fd3c --- /dev/null +++ b/assets/index.html-WpXt5Cz7.js @@ -0,0 +1 @@ +import{_ as e,o as c,c as t}from"./app-aH6YcK-Q.js";const n={};function _(o,r){return c(),t("div")}const a=e(n,[["render",_],["__file","index.html.vue"]]);export{a as default}; diff --git a/assets/index.html-zPqCtEf7.js b/assets/index.html-zPqCtEf7.js new file mode 100644 index 0000000..ff4ec75 --- /dev/null +++ b/assets/index.html-zPqCtEf7.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-8daa1a0e","path":"/","title":"","lang":"en-US","frontmatter":{"home":true,"navbar":false,"sidebar":false,"title":null,"heroAlt":null,"heroText":null,"tagline":"Select a language","actions":[{"text":"English","link":"/en/","type":"secondary"},{"text":"简体中文","link":"/zh-cn/","type":"secondary"}],"footer":"Apache-2.0 License | Copyright (C) 2019 HighCapable"},"headers":[],"git":{"updatedTime":1762849016000,"contributors":[{"name":"fankesyooni","email":"qzmmcn@163.com","commits":1}]},"filePathRelative":"index.md"}');export{e as data}; diff --git a/assets/quick-start.html-7AxcUCW_.js b/assets/quick-start.html-7AxcUCW_.js new file mode 100644 index 0000000..027851e --- /dev/null +++ b/assets/quick-start.html-7AxcUCW_.js @@ -0,0 +1 @@ +const i=JSON.parse('{"key":"v-72889797","path":"/en/guide/quick-start.html","title":"Quick Start","lang":"en-US","frontmatter":{},"headers":[{"level":2,"title":"Deploy Plugin","slug":"deploy-plugin","link":"#deploy-plugin","children":[]},{"level":2,"title":"Feature Configuration","slug":"feature-configuration","link":"#feature-configuration","children":[{"level":3,"title":"Common Configuration","slug":"common-configuration","link":"#common-configuration","children":[]},{"level":3,"title":"Build Script Configuration","slug":"build-script-configuration","link":"#build-script-configuration","children":[]},{"level":3,"title":"Android Project Configuration","slug":"android-project-configuration","link":"#android-project-configuration","children":[]},{"level":3,"title":"JVM Project Configuration","slug":"jvm-project-configuration","link":"#jvm-project-configuration","children":[]},{"level":3,"title":"Kotlin Multiplatform Project Configuration","slug":"kotlin-multiplatform-project-configuration","link":"#kotlin-multiplatform-project-configuration","children":[]}]},{"level":2,"title":"Usage Examples","slug":"usage-examples","link":"#usage-examples","children":[]},{"level":2,"title":"Possible Issues","slug":"possible-issues","link":"#possible-issues","children":[]},{"level":2,"title":"Limitations","slug":"limitations","link":"#limitations","children":[]}],"git":{"updatedTime":1763223336000,"contributors":[{"name":"fankesyooni","email":"qzmmcn@163.com","commits":5}]},"filePathRelative":"en/guide/quick-start.md"}');export{i as data}; diff --git a/assets/quick-start.html-f_E-gIx7.js b/assets/quick-start.html-f_E-gIx7.js new file mode 100644 index 0000000..b31d6b0 --- /dev/null +++ b/assets/quick-start.html-f_E-gIx7.js @@ -0,0 +1,493 @@ +import{_ as s,o as n,c as a,e}from"./app-aH6YcK-Q.js";const l={},o=e(`Quick Start
Integrate
Gropifyinto your project.
Deploy Plugin
Gropify dependencies are published on Maven Central and our public repository. You can configure the repository as follows.
We recommend using Gradle version 7.x.x or higher, and recommend using Kotlin DSL as the Gradle build script language. This documentation will no longer detail how to use it in Groovy DSL.
We recommend using the new pluginManagement method for deployment, which is a feature added since Gradle version 7.x.x.
If your project is still using buildscript for management, we recommend migrating to the new method. Instructions for the old version will no longer be provided here.
First, configure the plugin repository in your project's settings.gradle.kts.
The following example
pluginManagement {
+ repositories {
+ gradlePluginPortal() // Optional
+ google() // Optional
+ mavenCentral() // Required
+ // (Optional) You can add this URL to use our public repository
+ // This repository is added as an alternative when Sonatype-OSS fails to publish dependencies
+ // For details, please visit: https://github.com/HighCapable/maven-repository
+ maven("https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases")
+ }
+}
+Then add the Gropify plugin dependency in plugin in settings.gradle.kts. Please note do not add apply false after it.
The following example
plugins {
+ id("com.highcapable.gropify") version "<version>"
+}
+Please replace <version> with the version shown at the top of this section.
After completing the above configuration, run Gradle sync once.
Gropify will automatically search for gradle.properties files in the root project and each subproject, read the property key-values in them, and generate corresponding code for each project.
Notice
Gropify can only be applied to settings.gradle.kts, configuring it once will take effect globally. Please do not apply it to build.gradle.kts, otherwise the functionality will be invalid.
Feature Configuration
You can configure Gropify to implement customization and personalized features.
Gropify provides relatively rich customizable features. Below are the descriptions and configuration methods for these features.
Please add the gropify method block in your settings.gradle.kts to start configuring Gropify.
To use in Groovy DSL, please change all variable = to spaces, remove is before Enabled.
If you encounter a Gradle DSL method not found error, the solution is to migrate to Kotlin DSL.
If you don't want to use Kotlin DSL entirely, you can also migrate only settings.gradle to settings.gradle.kts.
The following example
gropify {
+ // Enable Gropify, setting it to \`false\` will disable all features.
+ isEnabled = true
+
+ // Whether to enable debug mode.
+ //
+ // You can help us identify the problem by enabling this option
+ // to print more debugging information in the logs.
+ //
+ // - Note: THIS IS ONLY FOR DEBUGGING!
+ // The debug log will contain your local environment,
+ // which may contain sensitive information.
+ // Please be sure to protect this information.
+ debugMode = false
+}
+Gropify's configuration mode is divided into three types: global global configuration, and rootProject, projects root project and subproject configuration.
You can continue to configure and integrate the configuration of the parent project in the child code blocks.
All configurations below are performed in the gropify method block.
The following example
// Global configuration.
+//
+// You can modify configurations in all projects in the global configuration.
+// Configurations 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 methods of root project and subprojects below.
+global {
+ // Common configuration.
+ common {
+ // Configure "common".
+ }
+
+ // Build script configuration.
+ buildscript {
+ // Configure "buildscript".
+ }
+
+ // Android project configuration.
+ android {
+ // Configure "android".
+ }
+
+ // JVM project configuration.
+ jvm {
+ // Configure "jvm".
+ }
+
+ // Kotlin Multiplatform project configuration.
+ kmp {
+ // Configure "kmp".
+ }
+}
+
+// Root project configuration.
+//
+// This is a special configuration method block that can only be used for the root project.
+rootProject {
+ common {
+ // Configure "common".
+ }
+ buildscript {
+ // Configure "buildscript".
+ }
+ android {
+ // Configure "android".
+ }
+ jvm {
+ // Configure "jvm".
+ }
+ kmp {
+ // Configure "kmp".
+ }
+}
+
+// Other projects and subprojects configuration.
+//
+// Fill in the full name of the project you need to configure in the
+// method parameters to configure the corresponding project.
+//
+// If the current project is a subproject, you must include the ":" before
+// the subproject name, such as ":app".
+//
+// If the current project is a nested subproject, such as app → sub,
+// you need to use ":" to separate multiple subprojects, such as ":app:sub".
+//
+// The name of the root project cannot be used directly to configure subprojects,
+// please use "rootProject".
+//
+// You can configure multiple projects and subprojects at the same time by filling
+// in an array of full project names in the method parameters to
+// configure each corresponding project.
+projects(":app", ":modules:library1", ":modules:library2") {
+ common {
+ // Configure "common".
+ }
+ buildscript {
+ // Configure "buildscript".
+ }
+ android {
+ // Configure "android".
+ }
+ jvm {
+ // Configure "jvm".
+ }
+ kmp {
+ // Configure "kmp".
+ }
+}
+You can continue below to learn how to configure the features in each method block.
Common Configuration
Here you can configure related features for all configuration types at the same time. The configurations here will be applied down to Build Script Configuration, Android Project Configuration, JVM Project Configuration, Kotlin Multiplatform Project Configuration.
The following example
common {
+ // Enable feature.
+ //
+ // You can set [buildscript], [android], [jvm], [kmp] separately.
+ isEnabled = true
+
+ // Whether to exclude the non-string type key-values content.
+ //
+ // Enabled by default, when enabled, key-values and content that are not
+ // string types will be excluded from properties' key-values.
+ excludeNonStringValue = true
+
+ // Whether to use type auto conversion.
+ //
+ // Enabled by default, when enabled, the type in the properties' key-values will be
+ // automatically identified and converted to the corresponding type.
+ //
+ // After enabling, if you want to force the content of a key-values to be a string type,
+ // you can use single quotes or double quotes to wrap the entire string.
+ //
+ // - Note: After disabled this function, the functions mentioned above will also be invalid.
+ useTypeAutoConversion = true
+
+ // Whether to use key-values content interpolation.
+ //
+ // Enabled by default, after enabling it will automatically identify
+ // the \`\${...}\` content in the properties' key-values content and replace it.
+ //
+ // Note: The interpolated content will only be looked up from the
+ // current (current configuration file) properties' key-values list.
+ useValueInterpolation = true
+
+ // Set exists property files.
+ //
+ // The property files will be automatically obtained from the root directory
+ // of the current root project,
+ // subproject and user directory according to the file name you set.
+ //
+ // By default, will add "gradle.properties" if [addDefault] is \`true\`.
+ //
+ // You can add multiple sets of property files name, they will be read in order.
+ //
+ // - Note: Generally there is no need to modify this setting,
+ // an incorrect file name will result in obtaining empty key-values content.
+ existsPropertyFiles(
+ "some-other-1.properties",
+ "some-other-2.properties",
+ addDefault = true
+ )
+
+ // Set a permanent list of properties' key-values.
+ //
+ // Here you can set some key-values that must exist, these key-values will be
+ // generated regardless of whether they can be obtained from the properties' key-values.
+ //
+ // These keys use the content of the properties' key if it exists,
+ // use the content set here if it does not exist.
+ //
+ // - Note: Special symbols and spaces cannot exist in properties' key names,
+ // otherwise the generation may fail.
+ permanentKeyValues(
+ "permanent.some.key1" to "some_value_1",
+ "permanent.some.key2" to "some_value_2"
+ )
+
+ // Set a replacement list of properties' key-values.
+ //
+ // Here you can set some key-values that need to be replaced, these key-values
+ // will be replaced the existing properties' key-values, if not exist, they will be ignored.
+ //
+ // The key-values set here will also overwrite the key-values set in [permanentKeyValues].
+ replacementKeyValues(
+ "some.key1" to "new.value1",
+ "some.key2" to "new.value2"
+ )
+
+ // Set a key list of properties' key-values name that need to be excluded.
+ //
+ // Here you can set some key names that you want to exclude from
+ // known properties' key-values.
+ //
+ // These keys are excluded if they are present in the properties' key,
+ // will not appear in the generated code.
+ //
+ // - Note: If you exclude key-values set in [permanentKeyValues], then they will
+ // only change to the initial key-values content you set and continue to exist.
+ excludeKeys(
+ "exclude.some.key1",
+ "exclude.some.key2"
+ )
+
+ // Set a key list of properties' key-values name that need to be included.
+ //
+ // Here you can set some key value names that you want to include from
+ // known properties' key-values.
+ //
+ // These keys are included if the properties' key exists,
+ // unincluded keys will not appear in the generated code.
+ includeKeys(
+ "include.some.key1",
+ "include.some.key2"
+ )
+
+ // Set properties' key-values rules.
+ //
+ // You can set up a set of key-values rules,
+ // use [ValueRule] to create new rule for parsing the obtained key-values content.
+ //
+ // These key-values rules are applied when properties' keys exist.
+ keyValuesRules(
+ "some.key1" to ValueRule { if (it.contains("_")) it.replace("_", "-") else it },
+ "some.key2" to ValueRule { "$it-value" },
+ // You can also specify the expected type class,
+ // the type you specify will be used during generation,
+ // and an exception will be thrown if the type cannot be converted correctly.
+ // If the [useTypeAutoConversion] is not enabled, this parameter will be ignored.
+ "some.key3" to ValueRule(Int::class)
+ )
+
+ // Set where to find properties' key-values.
+ //
+ // Defaults are [GropifyLocation.CurrentProject], [GropifyLocation.RootProject].
+ //
+ // You can set this up using the following types.
+ //
+ // - [GropifyLocation.CurrentProject]
+ // - [GropifyLocation.RootProject]
+ // - [GropifyLocation.Global]
+ // - [GropifyLocation.System]
+ // - [GropifyLocation.SystemEnv]
+ //
+ // We will generate properties' key-values in sequence from the locations you set,
+ // the order of the generation locations follows the order you set.
+ //
+ // - Risk warning: [GropifyLocation.Global], [GropifyLocation.System],
+ // [GropifyLocation.SystemEnv] may have keys and certificates,
+ // please manage the generated code carefully.
+ locations(GropifyLocation.CurrentProject, GropifyLocation.RootProject)
+}
+Tips
When referencing GropifyLocation, the build script may generate the following at the top of the build script when used with IDE auto-import.
import com.highcapable.gropify.plugin.config.type.GropifyLocation
+Gropify does alias processing for this, you can directly delete this import statement.
Build Script Configuration
The code generated in the build script can be directly used by the current build.gradle.kts, build.gradle.
The configuration here includes the configuration in common, and you can override it.
The following example
buildscript {
+ // Custom buildscript extension name.
+ //
+ // Default is "gropify".
+ extensionName = "gropify"
+}
+Notice
Gradle also has a buildscript method block, please be careful to use the correct DSL level.
Android Project Configuration
The content in this configuration block only takes effect for projects with AGP.
The configuration here includes the configuration in common, and you can override it.
The following example
android {
+ // Custom generated directory path.
+ //
+ // You can fill in the path relative to the current project.
+ //
+ // Format example: "path/to/your/src/main", the "src/main" is a fixed suffix.
+ //
+ // Default is "build/generated/gropify/src/main".
+ //
+ // We recommend that you set the generated path under the "build" directory,
+ // which is ignored by version control systems by default.
+ generateDirPath = "build/generated/gropify"
+
+ // Custom deployment \`sourceSet\` name.
+ //
+ // If your project source code deployment name is not default, you can customize it here.
+ //
+ // Default is "main".
+ sourceSetName = "main"
+
+ // Custom generated package name.
+ //
+ // Android projects use the \`namespace\` in the \`android\` configuration method block
+ // by default.
+ //
+ // The "generated" is a fixed suffix that avoids conflicts with your own namespaces,
+ // if you don't want this suffix, you can refer to [isIsolationEnabled].
+ packageName = "com.example.mydemo"
+
+ // Custom generated class name.
+ //
+ // Default is use the name of the current project.
+ //
+ // The "Properties" is a fixed suffix to distinguish it from your own class names.
+ className = "MyDemo"
+
+ // Whether to use Kotlin language generation.
+ //
+ // Enabled by default, when enabled will generate Kotlin code,
+ // disabled will generate Java code.
+ //
+ // - Note: This option will be disabled when this project is a pure Java project.
+ useKotlin = true
+
+ // Whether to enable restricted access.
+ //
+ // Disabled by default, when enabled will add the \`internal\` modifier to
+ // generated Kotlin classes or remove the \`public\` modifier to generated Java classes.
+ isRestrictedAccessEnabled = false
+
+ // Whether to enable code isolation.
+ //
+ // Enabled by default, when enabled will generate code in an
+ // isolated package suffix "generated" to avoid conflicts with other projects that
+ // also use or not only Gropify to generate code.
+ //
+ // - Note: If you disable this option, please make sure that there are no other projects
+ // that also use or not only Gropify to generate code to avoid conflicts.
+ isIsolationEnabled = true
+
+ // Whether to use manifest placeholders' generation.
+ //
+ // Disabled by default, when enabled will synchronize the properties' key-values
+ // to the \`manifestPlaceholders\` in the \`android\` configuration method block.
+ manifestPlaceholders = false
+}
+JVM Project Configuration
The content in this configuration block only takes effect for pure JVM projects (including Kotlin and Java projects). For Android projects, please refer to Android Project Configuration for configuration.
The configuration here includes the configuration in common, and you can override it.
The following example
jvm {
+ // Custom generated directory path.
+ //
+ // You can fill in the path relative to the current project.
+ //
+ // Format example: "path/to/your/src/main", the "src/main" is a fixed suffix.
+ //
+ // Default is "build/generated/gropify/src/main".
+ //
+ // We recommend that you set the generated path under the "build" directory,
+ // which is ignored by version control systems by default.
+ generateDirPath = "build/generated/gropify"
+
+ // Custom deployment \`sourceSet\` name.
+ //
+ // If your project source code deployment name is not default, you can customize it here.
+ //
+ // Default is "main".
+ sourceSetName = "main"
+
+ // Custom generated package name.
+ //
+ // Java, Kotlin projects use the \`project.group\` of the project settings by default.
+ //
+ // The "generated" is a fixed suffix that avoids conflicts with your own namespaces,
+ // if you don't want this suffix, you can refer to [isIsolationEnabled].
+ packageName = "com.example.mydemo"
+
+ // Custom generated class name.
+ //
+ // Default is use the name of the current project.
+ //
+ // The "Properties" is a fixed suffix to distinguish it from your own class names.
+ className = "MyDemo"
+
+ // Whether to use Kotlin language generation.
+ //
+ // Enabled by default, when enabled will generate Kotlin code,
+ // disabled will generate Java code.
+ //
+ // - Note: This option will be disabled when this project is a pure Java project.
+ useKotlin = true
+
+ // Whether to enable restricted access.
+ //
+ // Disabled by default, when enabled will add the \`internal\` modifier to
+ // generated Kotlin classes or remove the \`public\` modifier to generated Java classes.
+ isRestrictedAccessEnabled = false
+
+ // Whether to enable code isolation.
+ //
+ // Enabled by default, when enabled will generate code in an
+ // isolated package suffix "generated" to avoid conflicts with other projects that
+ // also use or not only Gropify to generate code.
+ //
+ // - Note: If you disable this option, please make sure that there are no other projects
+ // that also use or not only Gropify to generate code to avoid conflicts.
+ isIsolationEnabled = true
+}
+Kotlin Multiplatform Project Configuration
The content in this configuration block only takes effect for projects with the Kotlin Multiplatform plugin.
The configuration here includes the configuration in common, and you can override it.
The following example
kmp {
+ // Custom generated directory path.
+ //
+ // You can fill in the path relative to the current project.
+ //
+ // Format example: "path/to/your/src/main", the "src/main" is a fixed suffix.
+ //
+ // Default is "build/generated/gropify/src/main".
+ //
+ // We recommend that you set the generated path under the "build" directory,
+ // which is ignored by version control systems by default.
+ generateDirPath = "build/generated/gropify"
+
+ // Custom deployment \`sourceSet\` name.
+ //
+ // If your project source code deployment name is not default, you can customize it here.
+ //
+ // Default is "commonMain".
+ sourceSetName = "commonMain"
+
+ // Custom generated package name.
+ //
+ // Kotlin Multiplatform projects use the \`project.group\` of the project settings
+ // by default.
+ //
+ // In a Kotlin Multiplatform project, if the AGP plugin is also applied,
+ // the \`namespace\` will still be used as the package name by default.
+ //
+ // The "generated" is a fixed suffix that avoids conflicts with your own namespaces,
+ // if you don't want this suffix, you can refer to [isIsolationEnabled].
+ packageName = "com.example.mydemo"
+
+ // Custom generated class name.
+ //
+ // Default is use the name of the current project.
+ //
+ // The "Properties" is a fixed suffix to distinguish it from your own class names.
+ className = "MyDemo"
+
+ // Whether to enable restricted access.
+ //
+ // Disabled by default, when enabled will add the \`internal\` modifier to
+ // generated Kotlin classes.
+ isRestrictedAccessEnabled = false
+
+ // Whether to enable code isolation.
+ //
+ // Enabled by default, when enabled will generate code in an
+ // isolated package suffix "generated" to avoid conflicts with other projects that
+ // also use or not only Gropify to generate code.
+ //
+ // - Note: If you disable this option, please make sure that there are no other projects
+ // that also use or not only Gropify to generate code to avoid conflicts.
+ isIsolationEnabled = true
+}
+Usage Examples
Below is a project's gradle.properties configuration file.
The following example
project.groupName=com.highcapable.gropifydemo
+project.description=Hello Gropify Demo!
+project.version=1.0.0
+In the build script build.gradle.kts, we can directly use these key-values as shown below.
Here is an example of the Maven publish configuration section.
The following example
publications {
+ create<MavenPublication>("maven") {
+ groupId = gropify.project.groupName
+ version = gropify.project.version
+ pom.description.set(gropify.project.description)
+
+ from(components["java"])
+ }
+}
+Similarly, you can also call the generated key-values in the current project.
Kotlin
val groupName = GropifyDemoProperties.PROJECT_GROUP_NAME
+val description = GropifyDemoProperties.PROJECT_DESCRIPTION
+val version = GropifyDemoProperties.PROJECT_VERSION
+Java
var groupName = GropifyDemoProperties.PROJECT_GROUP_NAME;
+var description = GropifyDemoProperties.PROJECT_DESCRIPTION;
+var version = GropifyDemoProperties.PROJECT_VERSION;
+Let's take another example with an Android project.
In Android projects, many repetitive and fixed properties usually need to be configured, such as targetSdk.
The following example
project.namespace=com.highcapable.gropifydemo
+project.appName=Gropify Demo
+project.compileSdk=36
+project.targetSdk=36
+project.minSdk=26
+When you set useTypeAutoConversion = true, Gropify will try to convert it to the corresponding type during the entity class generation process under the default configuration.
For example, the key-values used below can be identified as string and integer types, which can be directly used by the project configuration.
The following example
android {
+ namespace = gropify.project.namespace
+ compileSdk = gropify.project.compileSdk
+
+ defaultConfig {
+ minSdk = gropify.project.minSdk
+ targetSdk = gropify.project.targetSdk
+ }
+}
+When you set manifestPlaceholders = true, Gropify will automatically synchronize these properties' key-values to manifestPlaceholders in the android configuration method block.
You can then use these placeholders directly in AndroidManifest.xml.
The following example
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+ <application
+ android:label="\${project.appName}"
+ android:icon="@mipmap/ic_launcher">
+
+ ...
+ </application>
+</manifest>
+You no longer need to use buildConfigField to add code to BuildConfig. With the property key-value code generated by Gropify, you can manage your project more flexibly.
You can also use interpolation \${...} in property key-values to reference each other's content, but recursive references are not allowed.
When you set useValueInterpolation = true, Gropify will automatically merge these referenced contents to the corresponding positions.
The following example
project.name=MyDemo
+project.developer.name=myname
+project.url=https://github.com/\${project.developer.name}/\${project.name}
+If you add GropifyLocation.SystemEnv to locations, you can also directly reference system environment variables.
The following example
# Use the $USER environment variable in Linux or macOS systems to get the current username.
+project.developer.name=\${USER}
+# Assume you have a system environment variable called SECRET_KEY (PLEASE BE SURE TO BE SAFE).
+project.secretKey=\${SECRET_KEY}
+Notice
This feature is provided by Gropify. Native gradle.properties does not support this feature.
The interpolated content is searched and replaced from top to bottom through the locations hierarchy. If there are duplicate key names, the last found content will be used for replacement.
Possible Issues
If your project only has a root project and no subprojects are imported, and the extension method cannot be generated normally at this time, you can migrate your root project to a subproject and import this subproject in settings.gradle.kts, which can solve this problem.
We generally recommend categorizing the functions of the project, with the root project only used to manage plugins and some configurations.
Limitations
Gropify cannot generate extension methods in settings.gradle.kts because it is upstream of Gropify.
快速开始
集成
Gropify到你的项目中。
部署插件
Gropify 的依赖发布在 Maven Central 和我们的公共存储库中，你可以使用如下方式配置存储库。
我们建议使用不低于 7.x.x 版本的 Gradle，并推荐使用 Kotlin DSL 作为 Gradle 构建脚本语言，文档中将不再详细介绍在 Groovy DSL 中的使用方法。
我们推荐使用 pluginManagement 新方式进行部署，它是自 Gradle 7.x.x 版本开始添加的功能。
如果你的项目依然在使用 buildscript 的方式进行管理，推荐迁移到新方式，这里将不再提供旧版本的使用方式说明。
首先，在你的项目 settings.gradle.kts 中配置插件的存储库。
示例如下
pluginManagement {
+ repositories {
+ gradlePluginPortal() // 可选
+ google() // 可选
+ mavenCentral() // 必须
+ // (可选) 你可以添加此 URL 以使用我们的公共存储库
+ // 当 Sonatype-OSS 发生故障无法发布依赖时，此存储库作为备选进行添加
+ // 详情请前往：https://github.com/HighCapable/maven-repository
+ maven("https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases")
+ }
+}
+然后在 settings.gradle.kts 中 plugin 添加 Gropify 插件依赖，请注意不要在后方加入 apply false。
示例如下
plugins {
+ id("com.highcapable.gropify") version "<version>"
+}
+请将 <version> 修改为此小结顶部显示的版本。
上述配置完成后，运行一次 Gradle Sync。
Gropify 将会自动搜索根项目和每个子项目中的 gradle.properties 文件，并读取其中的属性键值，为每个项目生成对应的代码。
注意
Gropify 只能被应用到 settings.gradle.kts 中，配置一次即可全局生效，请勿将其应用到 build.gradle.kts 中，否则功能将会无效。
功能配置
你可以对 Gropify 进行配置来实现自定义和个性化功能。
Gropify 为你提供了相对丰富的可自定义功能，下面是这些功能的说明与配置方法。
请在你的 settings.gradle.kts 中添加 gropify 方法块以开始配置 Gropify。
如需在 Groovy DSL 中使用，请将所有变量的 = 改为空格，并删除 Enabled 前方的 is 即可。
如果你遇到了 Gradle DSL method not found 错误，解决方案为迁移到 Kotlin DSL。
如果你不想全部使用 Kotlin DSL，你也可以仅将 settings.gradle 迁移到 settings.gradle.kts。
示例如下
gropify {
+ // 启用 Gropify，设置为 \`false\` 将禁用所有功能
+ isEnabled = true
+
+ // 是否启用调试模式
+ //
+ // 你可以通过启用此选项在日志中打印更多调试信息帮助我们定位问题
+ //
+ // - 注意: 此功能仅用于调试！
+ // 调试日志将包含你的本地环境，其中可能包含敏感信息，请务必保护好这些信息
+ debugMode = false
+}
+Gropify 的配置模式分为 global 全局配置和 rootProject、projects 根项目和子项目配置三种。
你可以在子项的代码块中继续配置和集成顶层项目的配置。
以下配置均在 gropify 方法块中进行。
示例如下
// 全局配置
+//
+// 你可以在全局配置中修改所有项目中的配置
+// 每个项目中未进行声明的配置将使用全局配置
+// 每个配置方法块中的功能完全一致
+//
+// 你可以参考下方根项目、子项目的配置方法
+global {
+ // 通用配置
+ common {
+ // 配置 "common"
+ }
+
+ // 构建脚本配置
+ buildscript {
+ // 配置 "buildscript"
+ }
+
+ // Android 项目配置
+ android {
+ // 配置 "android"
+ }
+
+ // JVM 项目配置
+ jvm {
+ // 配置 "jvm"
+ }
+
+ // Kotlin 多平台项目配置
+ kmp {
+ // 配置 "kmp"
+ }
+}
+
+// 根项目 (Root Project) 配置
+//
+// 这是一个特殊的配置方法块，只能用于根项目
+rootProject {
+ common {
+ // 配置 "common"
+ }
+ buildscript {
+ // 配置 "buildscript"
+ }
+ android {
+ // 配置 "android"
+ }
+ jvm {
+ // 配置 "jvm"
+ }
+ kmp {
+ // 配置 "kmp"
+ }
+}
+
+// 其它项目与子项目配置
+//
+// 在方法参数中填入需要配置的项目完整名称来配置对应的项目
+//
+// 如果当前项目是子项目，你必须填写子项目前面的 ":"，例如 ":app"
+//
+// 如果当前项目为嵌套型子项目，例如 app → sub
+// 此时你需要使用 ":" 来分隔多个子项目，例如 ":app:sub"
+//
+// 根项目的名称不能直接用来配置子项目，请使用 "rootProject"
+// 你可以同时进行多个项目与子项目配置，在方法参数中填入需要配置的项目完整名称数组来配置每个对应的项目
+projects(":app", ":modules:library1", ":modules:library2") {
+ common {
+ // 配置 "common"
+ }
+ buildscript {
+ // 配置 "buildscript"
+ }
+ android {
+ // 配置 "android"
+ }
+ jvm {
+ // 配置 "jvm"
+ }
+ kmp {
+ // 配置 "kmp"
+ }
+}
+你可以继续在下方了解如何配置每个方法块中的功能。
通用配置
在这里你可以同时配置所有配置类型的相关功能，这里的配置会向下应用到 构建脚本配置、Android 项目配置、JVM 项目配置、Kotlin 多平台项目配置 中。
示例如下
common {
+ // 启用功能
+ //
+ // 你可以分别对 [buildscript]、[android]、[jvm]、[kmp] 进行设置
+ isEnabled = true
+
+ // 是否排除非字符串类型的键值内容
+ //
+ // 默认启用，启用后将排除非字符串类型的键值和内容
+ excludeNonStringValue = true
+
+ // 是否使用类型自动转换
+ //
+ // 默认启用，启用后将自动识别属性键值中的类型并转换为对应类型
+ //
+ // 启用后，如果你想强制将键值内容设为字符串类型，
+ // 可以使用单引号或双引号包裹整个字符串
+ //
+ // - 注意: 禁用此功能后，上述功能也将失效
+ useTypeAutoConversion = true
+
+ // 是否使用键值内容插值
+ //
+ // 默认启用，启用后将自动识别属性键值内容中的 \`\${...}\` 并进行替换
+ //
+ // 注意: 插值内容仅会从当前 (当前配置文件) 属性键值列表中查找
+ useValueInterpolation = true
+
+ // 设置已存在的属性文件
+ //
+ // 属性文件将根据你设置的文件名自动从当前根项目、
+ // 子项目和用户目录的根目录获取
+ //
+ // 默认情况下，如果 [addDefault] 为 \`true\`，将添加 "gradle.properties"
+ //
+ // 你可以添加多组属性文件名，它们将按顺序读取
+ //
+ // - 注意: 通常无需修改此设置，错误的文件名将导致获取空键值内容
+ existsPropertyFiles(
+ "some-other-1.properties",
+ "some-other-2.properties",
+ addDefault = true
+ )
+
+ // 设置永久属性键值列表
+ //
+ // 在这里你可以设置一些必须存在的键值，无论是否能从属性键值中获取，
+ // 这些键值都将被生成
+ //
+ // 这些键如果存在于属性键中则使用属性键的内容，
+ // 如果不存在则使用这里设置的内容
+ //
+ // - 注意: 属性键名称中不能存在特殊符号和空格，否则可能导致生成失败
+ permanentKeyValues(
+ "permanent.some.key1" to "some_value_1",
+ "permanent.some.key2" to "some_value_2"
+ )
+
+ // 设置替换属性键值列表
+ //
+ // 在这里你可以设置一些需要替换的键值，这些键值
+ // 将替换现有的属性键值，如果不存在则忽略
+ //
+ // 这里设置的键值也会覆盖 [permanentKeyValues] 中设置的键值
+ replacementKeyValues(
+ "some.key1" to "new.value1",
+ "some.key2" to "new.value2"
+ )
+
+ // 设置需要排除的属性键值名称列表
+ //
+ // 在这里你可以设置一些要从已知属性键值中排除的键名称
+ //
+ // 如果这些键存在于属性键中则排除它们，
+ // 不会出现在生成的代码中
+ //
+ // - 注意: 如果你排除了 [permanentKeyValues] 中设置的键值，那么它们将
+ // 仅更改为你设置的初始键值内容并继续存在
+ excludeKeys(
+ "exclude.some.key1",
+ "exclude.some.key2"
+ )
+
+ // 设置需要包含的属性键值名称列表
+ //
+ // 在这里你可以设置一些要从已知属性键值中包含的键名称
+ //
+ // 如果属性键存在则包含这些键，未包含的键不会出现在生成的代码中
+ includeKeys(
+ "include.some.key1",
+ "include.some.key2"
+ )
+
+ // 设置属性键值规则
+ //
+ // 你可以设置一组键值规则，
+ // 使用 [ValueRule] 创建新规则来解析获取的键值内容
+ //
+ // 当属性键存在时应用这些键值规则
+ keyValuesRules(
+ "some.key1" to ValueRule { if (it.contains("_")) it.replace("_", "-") else it },
+ "some.key2" to ValueRule { "$it-value" },
+ // 你还可以指定期望的类型类，生成时将使用你指定的类型，
+ // 如果类型无法正确转换，将抛出异常
+ // 如果未启用 [useTypeAutoConversion]，此参数将被忽略
+ "some.key3" to ValueRule(Int::class)
+ )
+
+ // 设置查找属性键值的位置
+ //
+ // 默认为 [GropifyLocation.CurrentProject]、[GropifyLocation.RootProject]
+ //
+ // 你可以使用以下类型进行设置
+ //
+ // - [GropifyLocation.CurrentProject]
+ // - [GropifyLocation.RootProject]
+ // - [GropifyLocation.Global]
+ // - [GropifyLocation.System]
+ // - [GropifyLocation.SystemEnv]
+ //
+ // 我们将按顺序从你设置的位置生成属性键值，生成位置的顺序遵循你设置的顺序
+ //
+ // - 风险警告: [GropifyLocation.Global]、[GropifyLocation.System]、
+ // [GropifyLocation.SystemEnv] 可能包含密钥和证书，请谨慎管理生成的代码
+ locations(GropifyLocation.CurrentProject, GropifyLocation.RootProject)
+}
+小提示
在引用 GropifyLocation 时，构建脚本在配合 IDE 自动导入时可能会在构建脚本顶部生成以下内容。
import com.highcapable.gropify.plugin.config.type.GropifyLocation
+Gropify 对此做了 alias 处理，你可以直接删除此 import 语句。
构建脚本配置
在构建脚本中生成的代码可直接被当前 build.gradle.kts、build.gradle 使用。
这里的配置包括 common 中的配置，你可以对其进行复写。
示例如下
buildscript {
+ // 自定义构建脚本扩展名称
+ //
+ // 默认为 "gropify"
+ extensionName = "gropify"
+}
+注意
Gradle 中也有一个 buildscript 方法块，请注意使用正确的 DSL 层级。
Android 项目配置
此配置块中的内容仅对存在 AGP 的项目生效。
这里的配置包括 common 中的配置，你可以对其进行复写。
示例如下
android {
+ // 自定义生成的目录路径
+ //
+ // 你可以填写相对于当前项目的路径
+ //
+ // 格式示例: "path/to/your/src/main"，"src/main" 是固定后缀
+ //
+ // 默认为 "build/generated/gropify/src/main"
+ //
+ // 我们建议你将生成路径设置在 "build" 目录下，该目录默认被版本控制系统忽略
+ generateDirPath = "build/generated/gropify"
+
+ // 自定义部署 \`sourceSet\` 名称
+ //
+ // 如果你的项目源代码部署名称不是默认的，可以在此处自定义
+ //
+ // 默认为 "main"
+ sourceSetName = "main"
+
+ // 自定义生成的包名
+ //
+ // Android 项目默认使用 \`android\` 配置方法块中的 \`namespace\`
+ //
+ // "generated" 是固定后缀，用于避免与你自己的命名空间冲突，
+ // 如果你不想要此后缀，可以参考 [isIsolationEnabled]
+ packageName = "com.example.mydemo"
+
+ // 自定义生成的类名
+ //
+ // 默认使用当前项目的名称
+ //
+ // "Properties" 是固定后缀，用于与你自己的类名区分
+ className = "MyDemo"
+
+ // 是否使用 Kotlin 语言生成
+ //
+ // 默认启用，启用后将生成 Kotlin 代码，
+ // 禁用后将生成 Java 代码
+ //
+ // - 注意: 当此项目为纯 Java 项目时，此选项将被禁用
+ useKotlin = true
+
+ // 是否启用受限访问
+ //
+ // 默认禁用，启用后将为生成的 Kotlin 类添加 \`internal\` 修饰符，
+ // 或为生成的 Java 类移除 \`public\` 修饰符
+ isRestrictedAccessEnabled = false
+
+ // 是否启用代码隔离
+ //
+ // 默认启用，启用后将在隔离的包后缀 "generated" 中生成代码，
+ // 以避免与其他同样使用或不仅使用 Gropify 生成代码的项目冲突
+ //
+ // - 注意: 如果你禁用此选项，请确保没有其他同样使用或不仅使用
+ // Gropify 生成代码的项目，以避免冲突
+ isIsolationEnabled = true
+
+ // 是否使用清单占位符的生成。
+ //
+ // 默认禁用，启用后将同步属性的键值到 \`android\` 配置方法块中的 \`manifestPlaceholders\`
+ manifestPlaceholders = false
+}
+JVM 项目配置
此配置块中的内容仅对纯 JVM 项目生效 (包括 Kotlin、Java 项目)，如果是 Android 项目请参考 Android 项目配置 进行配置。
这里的配置包括 common 中的配置，你可以对其进行复写。
示例如下
jvm {
+ // 自定义生成的目录路径
+ //
+ // 你可以填写相对于当前项目的路径
+ //
+ // 格式示例: "path/to/your/src/main"，"src/main" 是固定后缀
+ //
+ // 默认为 "build/generated/gropify/src/main"
+ //
+ // 我们建议你将生成路径设置在 "build" 目录下，该目录默认被版本控制系统忽略
+ generateDirPath = "build/generated/gropify"
+
+ // 自定义部署 \`sourceSet\` 名称
+ //
+ // 如果你的项目源代码部署名称不是默认的，可以在此处自定义
+ //
+ // 默认为 "main"
+ sourceSetName = "main"
+
+ // 自定义生成的包名
+ //
+ // Java、Kotlin 项目默认使用项目设置的 \`project.group\`
+ //
+ // "generated" 是固定后缀，用于避免与你自己的命名空间冲突，
+ // 如果你不想要此后缀，可以参考 [isIsolationEnabled]
+ packageName = "com.example.mydemo"
+
+ // 自定义生成的类名
+ //
+ // 默认使用当前项目的名称
+ //
+ // "Properties" 是固定后缀，用于与你自己的类名区分
+ className = "MyDemo"
+
+ // 是否使用 Kotlin 语言生成
+ //
+ // 默认启用，启用后将生成 Kotlin 代码，
+ // 禁用后将生成 Java 代码
+ //
+ // - 注意: 当此项目为纯 Java 项目时，此选项将被禁用
+ useKotlin = true
+
+ // 是否启用受限访问
+ //
+ // 默认禁用，启用后将为生成的 Kotlin 类添加 \`internal\` 修饰符，
+ // 或为生成的 Java 类移除 \`public\` 修饰符
+ isRestrictedAccessEnabled = false
+
+ // 是否启用代码隔离
+ //
+ // 默认启用，启用后将在隔离的包后缀 "generated" 中生成代码，
+ // 以避免与其他同样使用或不仅使用 Gropify 生成代码的项目冲突
+ //
+ // - 注意: 如果你禁用此选项，请确保没有其他同样使用或不仅使用
+ // Gropify 生成代码的项目，以避免冲突
+ isIsolationEnabled = true
+}
+Kotlin 多平台项目配置
此配置块中的内容仅对含有 Kotlin Multiplatform 插件的项目生效。
这里的配置包括 common 中的配置，你可以对其进行复写。
kmp {
+ // 自定义生成的目录路径
+ //
+ // 你可以填写相对于当前项目的路径
+ //
+ // 格式示例: "path/to/your/src/main"，"src/main" 是固定后缀
+ //
+ // 默认为 "build/generated/gropify/src/main"
+ //
+ // 我们建议你将生成路径设置在 "build" 目录下，该目录默认被版本控制系统忽略
+ generateDirPath = "build/generated/gropify"
+
+ // 自定义部署 \`sourceSet\` 名称
+ //
+ // 如果你的项目源代码部署名称不是默认的，可以在此处自定义。
+ //
+ // 默认为 "commonMain"
+ sourceSetName = "commonMain"
+
+ // 自定义生成的包名
+ //
+ // Kotlin 多平台项目默认使用项目设置的 \`project.group\`
+ //
+ // 在 Kotlin 多平台项目中，如果同时应用了 AGP 插件，
+ // 仍将默认使用 \`namespace\` 作为包名
+ //
+ // "generated" 是固定后缀，用于避免与你自己的命名空间冲突，
+ // 如果你不想要此后缀，可以参考 [isIsolationEnabled]
+ packageName = "com.example.mydemo"
+
+ // 自定义生成的类名
+ //
+ // 默认使用当前项目的名称
+ //
+ // "Properties" 是固定后缀，用于与你自己的类名区分
+ className = "MyDemo"
+
+ // 是否启用受限访问
+ //
+ // 默认禁用，启用后将为生成的 Kotlin 类添加 \`internal\` 修饰符
+ isRestrictedAccessEnabled = false
+
+ // 是否启用代码隔离
+ //
+ // 默认启用，启用后将在隔离的包后缀 "generated" 中生成代码，
+ // 以避免与其他同样使用或不仅使用 Gropify 生成代码的项目冲突
+ //
+ // - 注意: 如果你禁用此选项，请确保没有其他同样使用或不仅使用
+ // Gropify 生成代码的项目，以避免冲突
+ isIsolationEnabled = true
+}
+使用示例
下面是一个项目的 gradle.properties 配置文件。
示例如下
project.groupName=com.highcapable.gropifydemo
+project.description=Hello Gropify Demo!
+project.version=1.0.0
+在构建脚本 build.gradle.kts 中，我们就可以如下所示这样直接去使用这些键值。
这里以 Maven 发布的配置部分举例。
示例如下
publications {
+ create<MavenPublication>("maven") {
+ groupId = gropify.project.groupName
+ version = gropify.project.version
+ pom.description.set(gropify.project.description)
+
+ from(components["java"])
+ }
+}
+同样地，你也可以在当前项目中调用生成的键值。
Kotlin
val groupName = GropifyDemoProperties.PROJECT_GROUP_NAME
+val description = GropifyDemoProperties.PROJECT_DESCRIPTION
+val version = GropifyDemoProperties.PROJECT_VERSION
+Java
var groupName = GropifyDemoProperties.PROJECT_GROUP_NAME;
+var description = GropifyDemoProperties.PROJECT_DESCRIPTION;
+var version = GropifyDemoProperties.PROJECT_VERSION;
+下面再以 Android 项目举例。
在 Android 项目中通常需要配置很多重复、固定的属性，例如 targetSdk。
示例如下
project.namespace=com.highcapable.gropifydemo
+project.appName=Gropify Demo
+project.compileSdk=36
+project.targetSdk=36
+project.minSdk=26
+当你设置了 useTypeAutoConversion = true 时，Gropify 在生成实体类过程在默认配置下将尝试将其转换为对应的类型。
例如下方所使用的键值，其类型可被识别为字符串和整型，可被项目配置直接使用。
示例如下
android {
+ namespace = gropify.project.namespace
+ compileSdk = gropify.project.compileSdk
+
+ defaultConfig {
+ minSdk = gropify.project.minSdk
+ targetSdk = gropify.project.targetSdk
+ }
+}
+当你设置了 manifestPlaceholders = true 时，Gropify 将自动将这些属性键值同步到 android 配置方法块中的 manifestPlaceholders。
此时你可以直接在 AndroidManifest.xml 中使用这些占位符。
示例如下
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+ <application
+ android:label="\${project.appName}"
+ android:icon="@mipmap/ic_launcher">
+
+ ...
+ </application>
+</manifest>
+你可以无需再使用 buildConfigField 向 BuildConfig 添加代码，有了 Gropify 生成的属性键值代码，你可以更加灵活地管理你的项目。
你还可以在属性键值中使用插值 \${...} 互相引用其中的内容，但不允许递归引用。
当你设置了 useValueInterpolation = true 时，Gropify 将自动合并这些引用的内容到对应位置。
示例如下
project.name=MyDemo
+project.developer.name=myname
+project.url=https://github.com/\${project.developer.name}/\${project.name}
+如果你在 locations 中添加了 GropifyLocation.SystemEnv，你还可以直接引用系统环境变量。
示例如下
# Linux 或 macOS 系统中使用 $USER 环境变量可以获取当前用户名
+project.developer.name=\${USER}
+# 假设你有一个名为 SECRET_KEY 的系统环境变量 (请确保安全)
+project.secretKey=\${SECRET_KEY}
+注意
这个特性是 Gropify 提供的，原生的 gradle.properties 并不支持此功能。
插值内容通过 locations 的层级自上而下进行查找替换，如果存在重复的键值名称，将使用最后查找到的内容进行替换。
可能遇到的问题
如果你的项目仅存在一个根项目，且没有导入任何子项目，此时如果扩展方法不能正常生成， 你可以将你的根项目迁移至子项目并在 settings.gradle.kts 中导入这个子项目，这样即可解决此问题。
我们一般推荐将项目的功能进行分类，根项目仅用来管理插件和一些配置。
局限性说明
Gropify 无法生成 settings.gradle.kts 中的扩展方法，因为这属于 Gropify 的上游。
GropifyAbout This Document
This document is powered by VuePress.
License
Apache License Version 2.0
+
+Copyright (C) 2019 HighCapable
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright © 2019 HighCapable
GropifyChangelog
The version update history of
Gropifyis recorded here.
Pay Attention
We will only maintain the latest API version. If you are using an outdated API version, you voluntarily renounce any possibility of maintenance.
Notice
To avoid translation time consumption, Changelog will use Google Translation from Chinese to English, please refer to the original text for actual reference.
Time zone of version release date: UTC+8
1.0.1 | 2025.11.16 latest
- Fixed the issue where
permanentKeyValueswas incorrectly configured toreplacementKeyValues - Optimized the automatic type conversion function for property key-values, fixed the problem of negative long integers being converted to integers
- Optimized log output function, added tags and text colors for each type of log
- Added
keyValueRulesto manually specify the type of property key-values, effective whenuseTypeAutoConversionis enabled - Enhanced debugging function, added detailed log output in debug mode
- Fixed the issue where
extensionNamewas judged as empty and illegal under default settings - Added judgment content for default extension method names that may cause conflicts
- Added
manifestPlaceholdersproperty key-value synchronization function toandroidconfiguration method block - Fixed the problem of Javapoet and Kotlinpoet processing special escape characters in source code generation
- Fixed other issues that may cause build script compilation failure
1.0.0 | 2025.11.11 stale
- The first version is submitted to Maven
GropifyContact Us
If you have any questions during usage, or have any constructive suggestions, you can contact us.
Join our developers group.
Find me on Twitter @fankesyooni.
Help with Maintenance
Thank you for choosing and using Gropify.
If you have code-related suggestions and requests, you can submit a Pull Request on GitHub.
GropifyLooking Toward the Future
The future is bright and uncertain, let us look forward to the future development potential of
Gropify.
Future Plans
Features that
Gropifymay add later are included here.
Support More Project Types
Gropify currently supports generating properties into the source code of Kotlin, Java, and Android projects. In the future, it may support more projects that can participate in Gradle builds, such as C/C++ (Android JNI), Swift, etc., to meet the needs of more developers.
GropifyIntroduction
Gropifyis a type-safe and modern properties plugin for Gradle.
Background
This plugin is designed for Gradle build scripts. It aims to bring properties similar to those in the gradle.properties file into build scripts in a type-safe way, avoiding problems that hard-coded strings might cause.
The project icon was designed by MaiTungTM. The name comes from GradlePropify, meaning a plugin for Gradle properties.
It is a brand-new project rebuilt from SweetProperty, borrowing previous design ideas and making it more polished and easier to use.
The configuration plan format of Gropify is similar to SweetProperty. If you are using SweetProperty, you can consider migrating to Gropify.
Usage
Gropify is mainly designed for Kotlin DSL build scripts. Groovy can directly use properties from the gradle.properties file as variables, but you can still use Gropify to achieve type-safe property access.
Gropify also supports generating properties (similar to those defined in a gradle.properties file) in a type-safe way into the source code of Kotlin, Java, and Android projects for use at application runtime—similar to Android's BuildConfig's buildConfigField feature.
Suppose we have the following gradle.properties file.
The following example
project.app.name=Gropify-Demo
+project.app.version=1.0.0
+Here is an example of calling the code automatically generated by Gropify.
Build Script (Kotlin DSL, Groovy DSL)
val appName = gropify.project.app.name
+val appVersion = gropify.project.app.version
+def appName = gropify.project.app.name
+def appVersion = gropify.project.app.version
+Source Code (Kotlin, Java)
val appName = MyAppProperties.PROJECT_APP_NAME
+val appVersion = MyAppProperties.PROJECT_APP_VERSION
+var appName = MyAppProperties.PROJECT_APP_NAME;
+var appVersion = MyAppProperties.PROJECT_APP_VERSION;
+Gropify also supports Kotlin Multiplatform projects, and you can use the generated property classes in the commonMain source set.
Language Requirement
It's recommended to use Kotlin DSL to configure your project's build scripts. Groovy is also supported, but in pure Groovy projects some configuration syntax may have compatibility issues.
In Groovy DSL, we will no longer be responsible for troubleshooting and fixing any issues that arise from using this plugin, and it may be completely unsupported in future versions.
Contribution
The maintenance of this project is inseparable from the support and contributions of all developers.
This project is currently in its early stages, and there may still be some problems or lack of functions you need.
If possible, feel free to submit a PR to contribute features you think are needed to this project or go to GitHub Issues to make suggestions to us.
GropifyQuick Start
Integrate
Gropifyinto your project.
Deploy Plugin
Gropify dependencies are published on Maven Central and our public repository. You can configure the repository as follows.
We recommend using Gradle version 7.x.x or higher, and recommend using Kotlin DSL as the Gradle build script language. This documentation will no longer detail how to use it in Groovy DSL.
We recommend using the new pluginManagement method for deployment, which is a feature added since Gradle version 7.x.x.
If your project is still using buildscript for management, we recommend migrating to the new method. Instructions for the old version will no longer be provided here.
First, configure the plugin repository in your project's settings.gradle.kts.
The following example
pluginManagement {
+ repositories {
+ gradlePluginPortal() // Optional
+ google() // Optional
+ mavenCentral() // Required
+ // (Optional) You can add this URL to use our public repository
+ // This repository is added as an alternative when Sonatype-OSS fails to publish dependencies
+ // For details, please visit: https://github.com/HighCapable/maven-repository
+ maven("https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases")
+ }
+}
+Then add the Gropify plugin dependency in plugin in settings.gradle.kts. Please note do not add apply false after it.
The following example
plugins {
+ id("com.highcapable.gropify") version "<version>"
+}
+Please replace <version> with the version shown at the top of this section.
After completing the above configuration, run Gradle sync once.
Gropify will automatically search for gradle.properties files in the root project and each subproject, read the property key-values in them, and generate corresponding code for each project.
Notice
Gropify can only be applied to settings.gradle.kts, configuring it once will take effect globally. Please do not apply it to build.gradle.kts, otherwise the functionality will be invalid.
Feature Configuration
You can configure Gropify to implement customization and personalized features.
Gropify provides relatively rich customizable features. Below are the descriptions and configuration methods for these features.
Please add the gropify method block in your settings.gradle.kts to start configuring Gropify.
To use in Groovy DSL, please change all variable = to spaces, remove is before Enabled.
If you encounter a Gradle DSL method not found error, the solution is to migrate to Kotlin DSL.
If you don't want to use Kotlin DSL entirely, you can also migrate only settings.gradle to settings.gradle.kts.
The following example
gropify {
+ // Enable Gropify, setting it to `false` will disable all features.
+ isEnabled = true
+
+ // Whether to enable debug mode.
+ //
+ // You can help us identify the problem by enabling this option
+ // to print more debugging information in the logs.
+ //
+ // - Note: THIS IS ONLY FOR DEBUGGING!
+ // The debug log will contain your local environment,
+ // which may contain sensitive information.
+ // Please be sure to protect this information.
+ debugMode = false
+}
+Gropify's configuration mode is divided into three types: global global configuration, and rootProject, projects root project and subproject configuration.
You can continue to configure and integrate the configuration of the parent project in the child code blocks.
All configurations below are performed in the gropify method block.
The following example
// Global configuration.
+//
+// You can modify configurations in all projects in the global configuration.
+// Configurations 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 methods of root project and subprojects below.
+global {
+ // Common configuration.
+ common {
+ // Configure "common".
+ }
+
+ // Build script configuration.
+ buildscript {
+ // Configure "buildscript".
+ }
+
+ // Android project configuration.
+ android {
+ // Configure "android".
+ }
+
+ // JVM project configuration.
+ jvm {
+ // Configure "jvm".
+ }
+
+ // Kotlin Multiplatform project configuration.
+ kmp {
+ // Configure "kmp".
+ }
+}
+
+// Root project configuration.
+//
+// This is a special configuration method block that can only be used for the root project.
+rootProject {
+ common {
+ // Configure "common".
+ }
+ buildscript {
+ // Configure "buildscript".
+ }
+ android {
+ // Configure "android".
+ }
+ jvm {
+ // Configure "jvm".
+ }
+ kmp {
+ // Configure "kmp".
+ }
+}
+
+// Other projects and subprojects configuration.
+//
+// Fill in the full name of the project you need to configure in the
+// method parameters to configure the corresponding project.
+//
+// If the current project is a subproject, you must include the ":" before
+// the subproject name, such as ":app".
+//
+// If the current project is a nested subproject, such as app → sub,
+// you need to use ":" to separate multiple subprojects, such as ":app:sub".
+//
+// The name of the root project cannot be used directly to configure subprojects,
+// please use "rootProject".
+//
+// You can configure multiple projects and subprojects at the same time by filling
+// in an array of full project names in the method parameters to
+// configure each corresponding project.
+projects(":app", ":modules:library1", ":modules:library2") {
+ common {
+ // Configure "common".
+ }
+ buildscript {
+ // Configure "buildscript".
+ }
+ android {
+ // Configure "android".
+ }
+ jvm {
+ // Configure "jvm".
+ }
+ kmp {
+ // Configure "kmp".
+ }
+}
+You can continue below to learn how to configure the features in each method block.
Common Configuration
Here you can configure related features for all configuration types at the same time. The configurations here will be applied down to Build Script Configuration, Android Project Configuration, JVM Project Configuration, Kotlin Multiplatform Project Configuration.
The following example
common {
+ // Enable feature.
+ //
+ // You can set [buildscript], [android], [jvm], [kmp] separately.
+ isEnabled = true
+
+ // Whether to exclude the non-string type key-values content.
+ //
+ // Enabled by default, when enabled, key-values and content that are not
+ // string types will be excluded from properties' key-values.
+ excludeNonStringValue = true
+
+ // Whether to use type auto conversion.
+ //
+ // Enabled by default, when enabled, the type in the properties' key-values will be
+ // automatically identified and converted to the corresponding type.
+ //
+ // After enabling, if you want to force the content of a key-values to be a string type,
+ // you can use single quotes or double quotes to wrap the entire string.
+ //
+ // - Note: After disabled this function, the functions mentioned above will also be invalid.
+ useTypeAutoConversion = true
+
+ // Whether to use key-values content interpolation.
+ //
+ // Enabled by default, after enabling it will automatically identify
+ // the `${...}` content in the properties' key-values content and replace it.
+ //
+ // Note: The interpolated content will only be looked up from the
+ // current (current configuration file) properties' key-values list.
+ useValueInterpolation = true
+
+ // Set exists property files.
+ //
+ // The property files will be automatically obtained from the root directory
+ // of the current root project,
+ // subproject and user directory according to the file name you set.
+ //
+ // By default, will add "gradle.properties" if [addDefault] is `true`.
+ //
+ // You can add multiple sets of property files name, they will be read in order.
+ //
+ // - Note: Generally there is no need to modify this setting,
+ // an incorrect file name will result in obtaining empty key-values content.
+ existsPropertyFiles(
+ "some-other-1.properties",
+ "some-other-2.properties",
+ addDefault = true
+ )
+
+ // Set a permanent list of properties' key-values.
+ //
+ // Here you can set some key-values that must exist, these key-values will be
+ // generated regardless of whether they can be obtained from the properties' key-values.
+ //
+ // These keys use the content of the properties' key if it exists,
+ // use the content set here if it does not exist.
+ //
+ // - Note: Special symbols and spaces cannot exist in properties' key names,
+ // otherwise the generation may fail.
+ permanentKeyValues(
+ "permanent.some.key1" to "some_value_1",
+ "permanent.some.key2" to "some_value_2"
+ )
+
+ // Set a replacement list of properties' key-values.
+ //
+ // Here you can set some key-values that need to be replaced, these key-values
+ // will be replaced the existing properties' key-values, if not exist, they will be ignored.
+ //
+ // The key-values set here will also overwrite the key-values set in [permanentKeyValues].
+ replacementKeyValues(
+ "some.key1" to "new.value1",
+ "some.key2" to "new.value2"
+ )
+
+ // Set a key list of properties' key-values name that need to be excluded.
+ //
+ // Here you can set some key names that you want to exclude from
+ // known properties' key-values.
+ //
+ // These keys are excluded if they are present in the properties' key,
+ // will not appear in the generated code.
+ //
+ // - Note: If you exclude key-values set in [permanentKeyValues], then they will
+ // only change to the initial key-values content you set and continue to exist.
+ excludeKeys(
+ "exclude.some.key1",
+ "exclude.some.key2"
+ )
+
+ // Set a key list of properties' key-values name that need to be included.
+ //
+ // Here you can set some key value names that you want to include from
+ // known properties' key-values.
+ //
+ // These keys are included if the properties' key exists,
+ // unincluded keys will not appear in the generated code.
+ includeKeys(
+ "include.some.key1",
+ "include.some.key2"
+ )
+
+ // Set properties' key-values rules.
+ //
+ // You can set up a set of key-values rules,
+ // use [ValueRule] to create new rule for parsing the obtained key-values content.
+ //
+ // These key-values rules are applied when properties' keys exist.
+ keyValuesRules(
+ "some.key1" to ValueRule { if (it.contains("_")) it.replace("_", "-") else it },
+ "some.key2" to ValueRule { "$it-value" },
+ // You can also specify the expected type class,
+ // the type you specify will be used during generation,
+ // and an exception will be thrown if the type cannot be converted correctly.
+ // If the [useTypeAutoConversion] is not enabled, this parameter will be ignored.
+ "some.key3" to ValueRule(Int::class)
+ )
+
+ // Set where to find properties' key-values.
+ //
+ // Defaults are [GropifyLocation.CurrentProject], [GropifyLocation.RootProject].
+ //
+ // You can set this up using the following types.
+ //
+ // - [GropifyLocation.CurrentProject]
+ // - [GropifyLocation.RootProject]
+ // - [GropifyLocation.Global]
+ // - [GropifyLocation.System]
+ // - [GropifyLocation.SystemEnv]
+ //
+ // We will generate properties' key-values in sequence from the locations you set,
+ // the order of the generation locations follows the order you set.
+ //
+ // - Risk warning: [GropifyLocation.Global], [GropifyLocation.System],
+ // [GropifyLocation.SystemEnv] may have keys and certificates,
+ // please manage the generated code carefully.
+ locations(GropifyLocation.CurrentProject, GropifyLocation.RootProject)
+}
+Tips
When referencing GropifyLocation, the build script may generate the following at the top of the build script when used with IDE auto-import.
import com.highcapable.gropify.plugin.config.type.GropifyLocation
+Gropify does alias processing for this, you can directly delete this import statement.
Build Script Configuration
The code generated in the build script can be directly used by the current build.gradle.kts, build.gradle.
The configuration here includes the configuration in common, and you can override it.
The following example
buildscript {
+ // Custom buildscript extension name.
+ //
+ // Default is "gropify".
+ extensionName = "gropify"
+}
+Notice
Gradle also has a buildscript method block, please be careful to use the correct DSL level.
Android Project Configuration
The content in this configuration block only takes effect for projects with AGP.
The configuration here includes the configuration in common, and you can override it.
The following example
android {
+ // Custom generated directory path.
+ //
+ // You can fill in the path relative to the current project.
+ //
+ // Format example: "path/to/your/src/main", the "src/main" is a fixed suffix.
+ //
+ // Default is "build/generated/gropify/src/main".
+ //
+ // We recommend that you set the generated path under the "build" directory,
+ // which is ignored by version control systems by default.
+ generateDirPath = "build/generated/gropify"
+
+ // Custom deployment `sourceSet` name.
+ //
+ // If your project source code deployment name is not default, you can customize it here.
+ //
+ // Default is "main".
+ sourceSetName = "main"
+
+ // Custom generated package name.
+ //
+ // Android projects use the `namespace` in the `android` configuration method block
+ // by default.
+ //
+ // The "generated" is a fixed suffix that avoids conflicts with your own namespaces,
+ // if you don't want this suffix, you can refer to [isIsolationEnabled].
+ packageName = "com.example.mydemo"
+
+ // Custom generated class name.
+ //
+ // Default is use the name of the current project.
+ //
+ // The "Properties" is a fixed suffix to distinguish it from your own class names.
+ className = "MyDemo"
+
+ // Whether to use Kotlin language generation.
+ //
+ // Enabled by default, when enabled will generate Kotlin code,
+ // disabled will generate Java code.
+ //
+ // - Note: This option will be disabled when this project is a pure Java project.
+ useKotlin = true
+
+ // Whether to enable restricted access.
+ //
+ // Disabled by default, when enabled will add the `internal` modifier to
+ // generated Kotlin classes or remove the `public` modifier to generated Java classes.
+ isRestrictedAccessEnabled = false
+
+ // Whether to enable code isolation.
+ //
+ // Enabled by default, when enabled will generate code in an
+ // isolated package suffix "generated" to avoid conflicts with other projects that
+ // also use or not only Gropify to generate code.
+ //
+ // - Note: If you disable this option, please make sure that there are no other projects
+ // that also use or not only Gropify to generate code to avoid conflicts.
+ isIsolationEnabled = true
+
+ // Whether to use manifest placeholders' generation.
+ //
+ // Disabled by default, when enabled will synchronize the properties' key-values
+ // to the `manifestPlaceholders` in the `android` configuration method block.
+ manifestPlaceholders = false
+}
+JVM Project Configuration
The content in this configuration block only takes effect for pure JVM projects (including Kotlin and Java projects). For Android projects, please refer to Android Project Configuration for configuration.
The configuration here includes the configuration in common, and you can override it.
The following example
jvm {
+ // Custom generated directory path.
+ //
+ // You can fill in the path relative to the current project.
+ //
+ // Format example: "path/to/your/src/main", the "src/main" is a fixed suffix.
+ //
+ // Default is "build/generated/gropify/src/main".
+ //
+ // We recommend that you set the generated path under the "build" directory,
+ // which is ignored by version control systems by default.
+ generateDirPath = "build/generated/gropify"
+
+ // Custom deployment `sourceSet` name.
+ //
+ // If your project source code deployment name is not default, you can customize it here.
+ //
+ // Default is "main".
+ sourceSetName = "main"
+
+ // Custom generated package name.
+ //
+ // Java, Kotlin projects use the `project.group` of the project settings by default.
+ //
+ // The "generated" is a fixed suffix that avoids conflicts with your own namespaces,
+ // if you don't want this suffix, you can refer to [isIsolationEnabled].
+ packageName = "com.example.mydemo"
+
+ // Custom generated class name.
+ //
+ // Default is use the name of the current project.
+ //
+ // The "Properties" is a fixed suffix to distinguish it from your own class names.
+ className = "MyDemo"
+
+ // Whether to use Kotlin language generation.
+ //
+ // Enabled by default, when enabled will generate Kotlin code,
+ // disabled will generate Java code.
+ //
+ // - Note: This option will be disabled when this project is a pure Java project.
+ useKotlin = true
+
+ // Whether to enable restricted access.
+ //
+ // Disabled by default, when enabled will add the `internal` modifier to
+ // generated Kotlin classes or remove the `public` modifier to generated Java classes.
+ isRestrictedAccessEnabled = false
+
+ // Whether to enable code isolation.
+ //
+ // Enabled by default, when enabled will generate code in an
+ // isolated package suffix "generated" to avoid conflicts with other projects that
+ // also use or not only Gropify to generate code.
+ //
+ // - Note: If you disable this option, please make sure that there are no other projects
+ // that also use or not only Gropify to generate code to avoid conflicts.
+ isIsolationEnabled = true
+}
+Kotlin Multiplatform Project Configuration
The content in this configuration block only takes effect for projects with the Kotlin Multiplatform plugin.
The configuration here includes the configuration in common, and you can override it.
The following example
kmp {
+ // Custom generated directory path.
+ //
+ // You can fill in the path relative to the current project.
+ //
+ // Format example: "path/to/your/src/main", the "src/main" is a fixed suffix.
+ //
+ // Default is "build/generated/gropify/src/main".
+ //
+ // We recommend that you set the generated path under the "build" directory,
+ // which is ignored by version control systems by default.
+ generateDirPath = "build/generated/gropify"
+
+ // Custom deployment `sourceSet` name.
+ //
+ // If your project source code deployment name is not default, you can customize it here.
+ //
+ // Default is "commonMain".
+ sourceSetName = "commonMain"
+
+ // Custom generated package name.
+ //
+ // Kotlin Multiplatform projects use the `project.group` of the project settings
+ // by default.
+ //
+ // In a Kotlin Multiplatform project, if the AGP plugin is also applied,
+ // the `namespace` will still be used as the package name by default.
+ //
+ // The "generated" is a fixed suffix that avoids conflicts with your own namespaces,
+ // if you don't want this suffix, you can refer to [isIsolationEnabled].
+ packageName = "com.example.mydemo"
+
+ // Custom generated class name.
+ //
+ // Default is use the name of the current project.
+ //
+ // The "Properties" is a fixed suffix to distinguish it from your own class names.
+ className = "MyDemo"
+
+ // Whether to enable restricted access.
+ //
+ // Disabled by default, when enabled will add the `internal` modifier to
+ // generated Kotlin classes.
+ isRestrictedAccessEnabled = false
+
+ // Whether to enable code isolation.
+ //
+ // Enabled by default, when enabled will generate code in an
+ // isolated package suffix "generated" to avoid conflicts with other projects that
+ // also use or not only Gropify to generate code.
+ //
+ // - Note: If you disable this option, please make sure that there are no other projects
+ // that also use or not only Gropify to generate code to avoid conflicts.
+ isIsolationEnabled = true
+}
+Usage Examples
Below is a project's gradle.properties configuration file.
The following example
project.groupName=com.highcapable.gropifydemo
+project.description=Hello Gropify Demo!
+project.version=1.0.0
+In the build script build.gradle.kts, we can directly use these key-values as shown below.
Here is an example of the Maven publish configuration section.
The following example
publications {
+ create<MavenPublication>("maven") {
+ groupId = gropify.project.groupName
+ version = gropify.project.version
+ pom.description.set(gropify.project.description)
+
+ from(components["java"])
+ }
+}
+Similarly, you can also call the generated key-values in the current project.
Kotlin
val groupName = GropifyDemoProperties.PROJECT_GROUP_NAME
+val description = GropifyDemoProperties.PROJECT_DESCRIPTION
+val version = GropifyDemoProperties.PROJECT_VERSION
+Java
var groupName = GropifyDemoProperties.PROJECT_GROUP_NAME;
+var description = GropifyDemoProperties.PROJECT_DESCRIPTION;
+var version = GropifyDemoProperties.PROJECT_VERSION;
+Let's take another example with an Android project.
In Android projects, many repetitive and fixed properties usually need to be configured, such as targetSdk.
The following example
project.namespace=com.highcapable.gropifydemo
+project.appName=Gropify Demo
+project.compileSdk=36
+project.targetSdk=36
+project.minSdk=26
+When you set useTypeAutoConversion = true, Gropify will try to convert it to the corresponding type during the entity class generation process under the default configuration.
For example, the key-values used below can be identified as string and integer types, which can be directly used by the project configuration.
The following example
android {
+ namespace = gropify.project.namespace
+ compileSdk = gropify.project.compileSdk
+
+ defaultConfig {
+ minSdk = gropify.project.minSdk
+ targetSdk = gropify.project.targetSdk
+ }
+}
+When you set manifestPlaceholders = true, Gropify will automatically synchronize these properties' key-values to manifestPlaceholders in the android configuration method block.
You can then use these placeholders directly in AndroidManifest.xml.
The following example
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+ <application
+ android:label="${project.appName}"
+ android:icon="@mipmap/ic_launcher">
+
+ ...
+ </application>
+</manifest>
+You no longer need to use buildConfigField to add code to BuildConfig. With the property key-value code generated by Gropify, you can manage your project more flexibly.
You can also use interpolation ${...} in property key-values to reference each other's content, but recursive references are not allowed.
When you set useValueInterpolation = true, Gropify will automatically merge these referenced contents to the corresponding positions.
The following example
project.name=MyDemo
+project.developer.name=myname
+project.url=https://github.com/${project.developer.name}/${project.name}
+If you add GropifyLocation.SystemEnv to locations, you can also directly reference system environment variables.
The following example
# Use the $USER environment variable in Linux or macOS systems to get the current username.
+project.developer.name=${USER}
+# Assume you have a system environment variable called SECRET_KEY (PLEASE BE SURE TO BE SAFE).
+project.secretKey=${SECRET_KEY}
+Notice
This feature is provided by Gropify. Native gradle.properties does not support this feature.
The interpolated content is searched and replaced from top to bottom through the locations hierarchy. If there are duplicate key names, the last found content will be used for replacement.
Possible Issues
If your project only has a root project and no subprojects are imported, and the extension method cannot be generated normally at this time, you can migrate your root project to a subproject and import this subproject in settings.gradle.kts, which can solve this problem.
We generally recommend categorizing the functions of the project, with the root project only used to manage plugins and some configurations.
Limitations
Gropify cannot generate extension methods in settings.gradle.kts because it is upstream of Gropify.
GropifyGropify
A type-safe and modern properties plugin for Gradle
+
+
+
diff --git a/zh-cn/about/about.html b/zh-cn/about/about.html
new file mode 100644
index 0000000..b57046e
--- /dev/null
+++ b/zh-cn/about/about.html
@@ -0,0 +1,49 @@
+
+
+
+
+
+
+
+
+
Gropify关于此文档
此文档由 VuePress 强力驱动。
许可证
Apache License Version 2.0
+
+Copyright (C) 2019 HighCapable
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+版权所有 © 2019 HighCapable
Gropify更新日志
这里记录了
Gropify的版本更新历史。
特别注意
我们只会对最新的 API 版本进行维护，若你正在使用过时的 API 版本则代表你自愿放弃一切维护的可能性。
1.0.1 | 2025.11.16 最新
- 修复
permanentKeyValues被错误地配置到replacementKeyValues的问题 - 优化属性键值的类型自动转换功能，修复负数长整型被转换为整型的问题
- 优化日志输出功能，加入每种日志的标签和文字颜色
- 新增
keyValueRules可手动指定属性键值的类型，在启用了useTypeAutoConversion时生效 - 增强调试功能，加入了调试模式下的详细日志输出
- 修复
extensionName在默认设置情况下被判断为空格式非法的问题 - 增加了可能造成冲突的默认扩展方法名称判断内容
android配置方法块新增manifestPlaceholders属性键值同步功能- 修复源代码生成 Javapoet 和 Kotlinpoet 处理特殊转义字符的问题
- 修复其它可能导致构建脚本编译失败的问题
1.0.0 | 2025.11.11 过旧
- 首个版本提交至 Maven
+
+
+
diff --git a/zh-cn/about/future.html b/zh-cn/about/future.html
new file mode 100644
index 0000000..c45f1aa
--- /dev/null
+++ b/zh-cn/about/future.html
@@ -0,0 +1,34 @@
+
+
+
+
+
+
+
+
+
Gropify展望未来
未来是美好的，也是不确定的，让我们共同期待
Gropify在未来的发展空间。
未来的计划
这里收录了
Gropify可能会在后期添加的功能。
支持更多项目类型
Gropify 目前支持将属性生成到 Kotlin、Java 和 Android 项目的源代码中，在未来可能会支持更多能够参与 Gradle 构建的项目，例如 C/C++ (Android JNI)、Swift 等，以满足更多开发者的需求。
Gropify介绍
Gropify是一个类型安全且现代化的 Gradle 属性插件。
背景
这是一个为 Gradle 构建脚本设计的插件，旨在将类似 gradle.properties 文件中的属性以类型安全的方式引入到构建脚本中，从而避免硬编码字符串可能带来的问题。
项目图标由 MaiTungTM 设计，名称取自 GradlePropify，意为针对 Gradle 属性的插件。
它是基于 SweetProperty 重构的全新项目，借鉴了以往的设计方案，使得其在原有基础上更加完善和易用。
Gropify 的配置方案与 SweetProperty 类似，如果你正在使用 SweetProperty，你可以考虑将其迁移到 Gropify。
用途
Gropify 主要针对 Kotlin DSL 构建脚本设计，Groovy 语言可以直接将 gradle.properties 文件中的属性作为变量使用，但是你也可以通过 Gropify 来实现类型安全的属性访问。
Gropify 同时支持将类似 gradle.properties 文件中的属性以类型安全的方式生成到 Kotlin、Java、Android 项目的源码中以供应用程序运行时使用，功能类似 Android 的 BuildConfig 中的 buildConfigField 功能。
假设我们有以下 gradle.properties 文件。
示例如下
project.app.name=Gropify-Demo
+project.app.version=1.0.0
+这是 Gropify 自动生成的代码调用示例。
构建脚本 (Kotlin DSL、Groovy DSL)
val appName = gropify.project.app.name
+val appVersion = gropify.project.app.version
+def appName = gropify.project.app.name
+def appVersion = gropify.project.app.version
+源代码 (Kotlin、Java)
val appName = MyAppProperties.PROJECT_APP_NAME
+val appVersion = MyAppProperties.PROJECT_APP_VERSION
+var appName = MyAppProperties.PROJECT_APP_NAME;
+var appVersion = MyAppProperties.PROJECT_APP_VERSION;
+Gropify 同样支持 Kotlin Multiplatform 项目，你可以在 commonMain 源集中使用生成的属性类。
语言要求
推荐使用 Kotlin DSL 来配置项目的构建脚本，Groovy 语言同样受支持，但在纯 Groovy 项目中部分配置语法可能存在兼容性问题。
在 Groovy DSL 中使用此插件发生的任何问题，我们都将不再负责排查和修复，并且在后期版本可能会完全不再支持 Groovy DSL。
功能贡献
本项目的维护离不开各位开发者的支持和贡献，目前这个项目处于初期阶段，可能依然存在一些问题或者缺少你需要的功能， 如果可能，欢迎提交 PR 为此项目贡献你认为需要的功能或前往 GitHub Issues 向我们提出建议。
Gropify快速开始
集成
Gropify到你的项目中。
部署插件
Gropify 的依赖发布在 Maven Central 和我们的公共存储库中，你可以使用如下方式配置存储库。
我们建议使用不低于 7.x.x 版本的 Gradle，并推荐使用 Kotlin DSL 作为 Gradle 构建脚本语言，文档中将不再详细介绍在 Groovy DSL 中的使用方法。
我们推荐使用 pluginManagement 新方式进行部署，它是自 Gradle 7.x.x 版本开始添加的功能。
如果你的项目依然在使用 buildscript 的方式进行管理，推荐迁移到新方式，这里将不再提供旧版本的使用方式说明。
首先，在你的项目 settings.gradle.kts 中配置插件的存储库。
示例如下
pluginManagement {
+ repositories {
+ gradlePluginPortal() // 可选
+ google() // 可选
+ mavenCentral() // 必须
+ // (可选) 你可以添加此 URL 以使用我们的公共存储库
+ // 当 Sonatype-OSS 发生故障无法发布依赖时，此存储库作为备选进行添加
+ // 详情请前往：https://github.com/HighCapable/maven-repository
+ maven("https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases")
+ }
+}
+然后在 settings.gradle.kts 中 plugin 添加 Gropify 插件依赖，请注意不要在后方加入 apply false。
示例如下
plugins {
+ id("com.highcapable.gropify") version "<version>"
+}
+请将 <version> 修改为此小结顶部显示的版本。
上述配置完成后，运行一次 Gradle Sync。
Gropify 将会自动搜索根项目和每个子项目中的 gradle.properties 文件，并读取其中的属性键值，为每个项目生成对应的代码。
注意
Gropify 只能被应用到 settings.gradle.kts 中，配置一次即可全局生效，请勿将其应用到 build.gradle.kts 中，否则功能将会无效。
功能配置
你可以对 Gropify 进行配置来实现自定义和个性化功能。
Gropify 为你提供了相对丰富的可自定义功能，下面是这些功能的说明与配置方法。
请在你的 settings.gradle.kts 中添加 gropify 方法块以开始配置 Gropify。
如需在 Groovy DSL 中使用，请将所有变量的 = 改为空格，并删除 Enabled 前方的 is 即可。
如果你遇到了 Gradle DSL method not found 错误，解决方案为迁移到 Kotlin DSL。
如果你不想全部使用 Kotlin DSL，你也可以仅将 settings.gradle 迁移到 settings.gradle.kts。
示例如下
gropify {
+ // 启用 Gropify，设置为 `false` 将禁用所有功能
+ isEnabled = true
+
+ // 是否启用调试模式
+ //
+ // 你可以通过启用此选项在日志中打印更多调试信息帮助我们定位问题
+ //
+ // - 注意: 此功能仅用于调试！
+ // 调试日志将包含你的本地环境，其中可能包含敏感信息，请务必保护好这些信息
+ debugMode = false
+}
+Gropify 的配置模式分为 global 全局配置和 rootProject、projects 根项目和子项目配置三种。
你可以在子项的代码块中继续配置和集成顶层项目的配置。
以下配置均在 gropify 方法块中进行。
示例如下
// 全局配置
+//
+// 你可以在全局配置中修改所有项目中的配置
+// 每个项目中未进行声明的配置将使用全局配置
+// 每个配置方法块中的功能完全一致
+//
+// 你可以参考下方根项目、子项目的配置方法
+global {
+ // 通用配置
+ common {
+ // 配置 "common"
+ }
+
+ // 构建脚本配置
+ buildscript {
+ // 配置 "buildscript"
+ }
+
+ // Android 项目配置
+ android {
+ // 配置 "android"
+ }
+
+ // JVM 项目配置
+ jvm {
+ // 配置 "jvm"
+ }
+
+ // Kotlin 多平台项目配置
+ kmp {
+ // 配置 "kmp"
+ }
+}
+
+// 根项目 (Root Project) 配置
+//
+// 这是一个特殊的配置方法块，只能用于根项目
+rootProject {
+ common {
+ // 配置 "common"
+ }
+ buildscript {
+ // 配置 "buildscript"
+ }
+ android {
+ // 配置 "android"
+ }
+ jvm {
+ // 配置 "jvm"
+ }
+ kmp {
+ // 配置 "kmp"
+ }
+}
+
+// 其它项目与子项目配置
+//
+// 在方法参数中填入需要配置的项目完整名称来配置对应的项目
+//
+// 如果当前项目是子项目，你必须填写子项目前面的 ":"，例如 ":app"
+//
+// 如果当前项目为嵌套型子项目，例如 app → sub
+// 此时你需要使用 ":" 来分隔多个子项目，例如 ":app:sub"
+//
+// 根项目的名称不能直接用来配置子项目，请使用 "rootProject"
+// 你可以同时进行多个项目与子项目配置，在方法参数中填入需要配置的项目完整名称数组来配置每个对应的项目
+projects(":app", ":modules:library1", ":modules:library2") {
+ common {
+ // 配置 "common"
+ }
+ buildscript {
+ // 配置 "buildscript"
+ }
+ android {
+ // 配置 "android"
+ }
+ jvm {
+ // 配置 "jvm"
+ }
+ kmp {
+ // 配置 "kmp"
+ }
+}
+你可以继续在下方了解如何配置每个方法块中的功能。
通用配置
在这里你可以同时配置所有配置类型的相关功能，这里的配置会向下应用到 构建脚本配置、Android 项目配置、JVM 项目配置、Kotlin 多平台项目配置 中。
示例如下
common {
+ // 启用功能
+ //
+ // 你可以分别对 [buildscript]、[android]、[jvm]、[kmp] 进行设置
+ isEnabled = true
+
+ // 是否排除非字符串类型的键值内容
+ //
+ // 默认启用，启用后将排除非字符串类型的键值和内容
+ excludeNonStringValue = true
+
+ // 是否使用类型自动转换
+ //
+ // 默认启用，启用后将自动识别属性键值中的类型并转换为对应类型
+ //
+ // 启用后，如果你想强制将键值内容设为字符串类型，
+ // 可以使用单引号或双引号包裹整个字符串
+ //
+ // - 注意: 禁用此功能后，上述功能也将失效
+ useTypeAutoConversion = true
+
+ // 是否使用键值内容插值
+ //
+ // 默认启用，启用后将自动识别属性键值内容中的 `${...}` 并进行替换
+ //
+ // 注意: 插值内容仅会从当前 (当前配置文件) 属性键值列表中查找
+ useValueInterpolation = true
+
+ // 设置已存在的属性文件
+ //
+ // 属性文件将根据你设置的文件名自动从当前根项目、
+ // 子项目和用户目录的根目录获取
+ //
+ // 默认情况下，如果 [addDefault] 为 `true`，将添加 "gradle.properties"
+ //
+ // 你可以添加多组属性文件名，它们将按顺序读取
+ //
+ // - 注意: 通常无需修改此设置，错误的文件名将导致获取空键值内容
+ existsPropertyFiles(
+ "some-other-1.properties",
+ "some-other-2.properties",
+ addDefault = true
+ )
+
+ // 设置永久属性键值列表
+ //
+ // 在这里你可以设置一些必须存在的键值，无论是否能从属性键值中获取，
+ // 这些键值都将被生成
+ //
+ // 这些键如果存在于属性键中则使用属性键的内容，
+ // 如果不存在则使用这里设置的内容
+ //
+ // - 注意: 属性键名称中不能存在特殊符号和空格，否则可能导致生成失败
+ permanentKeyValues(
+ "permanent.some.key1" to "some_value_1",
+ "permanent.some.key2" to "some_value_2"
+ )
+
+ // 设置替换属性键值列表
+ //
+ // 在这里你可以设置一些需要替换的键值，这些键值
+ // 将替换现有的属性键值，如果不存在则忽略
+ //
+ // 这里设置的键值也会覆盖 [permanentKeyValues] 中设置的键值
+ replacementKeyValues(
+ "some.key1" to "new.value1",
+ "some.key2" to "new.value2"
+ )
+
+ // 设置需要排除的属性键值名称列表
+ //
+ // 在这里你可以设置一些要从已知属性键值中排除的键名称
+ //
+ // 如果这些键存在于属性键中则排除它们，
+ // 不会出现在生成的代码中
+ //
+ // - 注意: 如果你排除了 [permanentKeyValues] 中设置的键值，那么它们将
+ // 仅更改为你设置的初始键值内容并继续存在
+ excludeKeys(
+ "exclude.some.key1",
+ "exclude.some.key2"
+ )
+
+ // 设置需要包含的属性键值名称列表
+ //
+ // 在这里你可以设置一些要从已知属性键值中包含的键名称
+ //
+ // 如果属性键存在则包含这些键，未包含的键不会出现在生成的代码中
+ includeKeys(
+ "include.some.key1",
+ "include.some.key2"
+ )
+
+ // 设置属性键值规则
+ //
+ // 你可以设置一组键值规则，
+ // 使用 [ValueRule] 创建新规则来解析获取的键值内容
+ //
+ // 当属性键存在时应用这些键值规则
+ keyValuesRules(
+ "some.key1" to ValueRule { if (it.contains("_")) it.replace("_", "-") else it },
+ "some.key2" to ValueRule { "$it-value" },
+ // 你还可以指定期望的类型类，生成时将使用你指定的类型，
+ // 如果类型无法正确转换，将抛出异常
+ // 如果未启用 [useTypeAutoConversion]，此参数将被忽略
+ "some.key3" to ValueRule(Int::class)
+ )
+
+ // 设置查找属性键值的位置
+ //
+ // 默认为 [GropifyLocation.CurrentProject]、[GropifyLocation.RootProject]
+ //
+ // 你可以使用以下类型进行设置
+ //
+ // - [GropifyLocation.CurrentProject]
+ // - [GropifyLocation.RootProject]
+ // - [GropifyLocation.Global]
+ // - [GropifyLocation.System]
+ // - [GropifyLocation.SystemEnv]
+ //
+ // 我们将按顺序从你设置的位置生成属性键值，生成位置的顺序遵循你设置的顺序
+ //
+ // - 风险警告: [GropifyLocation.Global]、[GropifyLocation.System]、
+ // [GropifyLocation.SystemEnv] 可能包含密钥和证书，请谨慎管理生成的代码
+ locations(GropifyLocation.CurrentProject, GropifyLocation.RootProject)
+}
+小提示
在引用 GropifyLocation 时，构建脚本在配合 IDE 自动导入时可能会在构建脚本顶部生成以下内容。
import com.highcapable.gropify.plugin.config.type.GropifyLocation
+Gropify 对此做了 alias 处理，你可以直接删除此 import 语句。
构建脚本配置
在构建脚本中生成的代码可直接被当前 build.gradle.kts、build.gradle 使用。
这里的配置包括 common 中的配置，你可以对其进行复写。
示例如下
buildscript {
+ // 自定义构建脚本扩展名称
+ //
+ // 默认为 "gropify"
+ extensionName = "gropify"
+}
+注意
Gradle 中也有一个 buildscript 方法块，请注意使用正确的 DSL 层级。
Android 项目配置
此配置块中的内容仅对存在 AGP 的项目生效。
这里的配置包括 common 中的配置，你可以对其进行复写。
示例如下
android {
+ // 自定义生成的目录路径
+ //
+ // 你可以填写相对于当前项目的路径
+ //
+ // 格式示例: "path/to/your/src/main"，"src/main" 是固定后缀
+ //
+ // 默认为 "build/generated/gropify/src/main"
+ //
+ // 我们建议你将生成路径设置在 "build" 目录下，该目录默认被版本控制系统忽略
+ generateDirPath = "build/generated/gropify"
+
+ // 自定义部署 `sourceSet` 名称
+ //
+ // 如果你的项目源代码部署名称不是默认的，可以在此处自定义
+ //
+ // 默认为 "main"
+ sourceSetName = "main"
+
+ // 自定义生成的包名
+ //
+ // Android 项目默认使用 `android` 配置方法块中的 `namespace`
+ //
+ // "generated" 是固定后缀，用于避免与你自己的命名空间冲突，
+ // 如果你不想要此后缀，可以参考 [isIsolationEnabled]
+ packageName = "com.example.mydemo"
+
+ // 自定义生成的类名
+ //
+ // 默认使用当前项目的名称
+ //
+ // "Properties" 是固定后缀，用于与你自己的类名区分
+ className = "MyDemo"
+
+ // 是否使用 Kotlin 语言生成
+ //
+ // 默认启用，启用后将生成 Kotlin 代码，
+ // 禁用后将生成 Java 代码
+ //
+ // - 注意: 当此项目为纯 Java 项目时，此选项将被禁用
+ useKotlin = true
+
+ // 是否启用受限访问
+ //
+ // 默认禁用，启用后将为生成的 Kotlin 类添加 `internal` 修饰符，
+ // 或为生成的 Java 类移除 `public` 修饰符
+ isRestrictedAccessEnabled = false
+
+ // 是否启用代码隔离
+ //
+ // 默认启用，启用后将在隔离的包后缀 "generated" 中生成代码，
+ // 以避免与其他同样使用或不仅使用 Gropify 生成代码的项目冲突
+ //
+ // - 注意: 如果你禁用此选项，请确保没有其他同样使用或不仅使用
+ // Gropify 生成代码的项目，以避免冲突
+ isIsolationEnabled = true
+
+ // 是否使用清单占位符的生成。
+ //
+ // 默认禁用，启用后将同步属性的键值到 `android` 配置方法块中的 `manifestPlaceholders`
+ manifestPlaceholders = false
+}
+JVM 项目配置
此配置块中的内容仅对纯 JVM 项目生效 (包括 Kotlin、Java 项目)，如果是 Android 项目请参考 Android 项目配置 进行配置。
这里的配置包括 common 中的配置，你可以对其进行复写。
示例如下
jvm {
+ // 自定义生成的目录路径
+ //
+ // 你可以填写相对于当前项目的路径
+ //
+ // 格式示例: "path/to/your/src/main"，"src/main" 是固定后缀
+ //
+ // 默认为 "build/generated/gropify/src/main"
+ //
+ // 我们建议你将生成路径设置在 "build" 目录下，该目录默认被版本控制系统忽略
+ generateDirPath = "build/generated/gropify"
+
+ // 自定义部署 `sourceSet` 名称
+ //
+ // 如果你的项目源代码部署名称不是默认的，可以在此处自定义
+ //
+ // 默认为 "main"
+ sourceSetName = "main"
+
+ // 自定义生成的包名
+ //
+ // Java、Kotlin 项目默认使用项目设置的 `project.group`
+ //
+ // "generated" 是固定后缀，用于避免与你自己的命名空间冲突，
+ // 如果你不想要此后缀，可以参考 [isIsolationEnabled]
+ packageName = "com.example.mydemo"
+
+ // 自定义生成的类名
+ //
+ // 默认使用当前项目的名称
+ //
+ // "Properties" 是固定后缀，用于与你自己的类名区分
+ className = "MyDemo"
+
+ // 是否使用 Kotlin 语言生成
+ //
+ // 默认启用，启用后将生成 Kotlin 代码，
+ // 禁用后将生成 Java 代码
+ //
+ // - 注意: 当此项目为纯 Java 项目时，此选项将被禁用
+ useKotlin = true
+
+ // 是否启用受限访问
+ //
+ // 默认禁用，启用后将为生成的 Kotlin 类添加 `internal` 修饰符，
+ // 或为生成的 Java 类移除 `public` 修饰符
+ isRestrictedAccessEnabled = false
+
+ // 是否启用代码隔离
+ //
+ // 默认启用，启用后将在隔离的包后缀 "generated" 中生成代码，
+ // 以避免与其他同样使用或不仅使用 Gropify 生成代码的项目冲突
+ //
+ // - 注意: 如果你禁用此选项，请确保没有其他同样使用或不仅使用
+ // Gropify 生成代码的项目，以避免冲突
+ isIsolationEnabled = true
+}
+Kotlin 多平台项目配置
此配置块中的内容仅对含有 Kotlin Multiplatform 插件的项目生效。
这里的配置包括 common 中的配置，你可以对其进行复写。
kmp {
+ // 自定义生成的目录路径
+ //
+ // 你可以填写相对于当前项目的路径
+ //
+ // 格式示例: "path/to/your/src/main"，"src/main" 是固定后缀
+ //
+ // 默认为 "build/generated/gropify/src/main"
+ //
+ // 我们建议你将生成路径设置在 "build" 目录下，该目录默认被版本控制系统忽略
+ generateDirPath = "build/generated/gropify"
+
+ // 自定义部署 `sourceSet` 名称
+ //
+ // 如果你的项目源代码部署名称不是默认的，可以在此处自定义。
+ //
+ // 默认为 "commonMain"
+ sourceSetName = "commonMain"
+
+ // 自定义生成的包名
+ //
+ // Kotlin 多平台项目默认使用项目设置的 `project.group`
+ //
+ // 在 Kotlin 多平台项目中，如果同时应用了 AGP 插件，
+ // 仍将默认使用 `namespace` 作为包名
+ //
+ // "generated" 是固定后缀，用于避免与你自己的命名空间冲突，
+ // 如果你不想要此后缀，可以参考 [isIsolationEnabled]
+ packageName = "com.example.mydemo"
+
+ // 自定义生成的类名
+ //
+ // 默认使用当前项目的名称
+ //
+ // "Properties" 是固定后缀，用于与你自己的类名区分
+ className = "MyDemo"
+
+ // 是否启用受限访问
+ //
+ // 默认禁用，启用后将为生成的 Kotlin 类添加 `internal` 修饰符
+ isRestrictedAccessEnabled = false
+
+ // 是否启用代码隔离
+ //
+ // 默认启用，启用后将在隔离的包后缀 "generated" 中生成代码，
+ // 以避免与其他同样使用或不仅使用 Gropify 生成代码的项目冲突
+ //
+ // - 注意: 如果你禁用此选项，请确保没有其他同样使用或不仅使用
+ // Gropify 生成代码的项目，以避免冲突
+ isIsolationEnabled = true
+}
+使用示例
下面是一个项目的 gradle.properties 配置文件。
示例如下
project.groupName=com.highcapable.gropifydemo
+project.description=Hello Gropify Demo!
+project.version=1.0.0
+在构建脚本 build.gradle.kts 中，我们就可以如下所示这样直接去使用这些键值。
这里以 Maven 发布的配置部分举例。
示例如下
publications {
+ create<MavenPublication>("maven") {
+ groupId = gropify.project.groupName
+ version = gropify.project.version
+ pom.description.set(gropify.project.description)
+
+ from(components["java"])
+ }
+}
+同样地，你也可以在当前项目中调用生成的键值。
Kotlin
val groupName = GropifyDemoProperties.PROJECT_GROUP_NAME
+val description = GropifyDemoProperties.PROJECT_DESCRIPTION
+val version = GropifyDemoProperties.PROJECT_VERSION
+Java
var groupName = GropifyDemoProperties.PROJECT_GROUP_NAME;
+var description = GropifyDemoProperties.PROJECT_DESCRIPTION;
+var version = GropifyDemoProperties.PROJECT_VERSION;
+下面再以 Android 项目举例。
在 Android 项目中通常需要配置很多重复、固定的属性，例如 targetSdk。
示例如下
project.namespace=com.highcapable.gropifydemo
+project.appName=Gropify Demo
+project.compileSdk=36
+project.targetSdk=36
+project.minSdk=26
+当你设置了 useTypeAutoConversion = true 时，Gropify 在生成实体类过程在默认配置下将尝试将其转换为对应的类型。
例如下方所使用的键值，其类型可被识别为字符串和整型，可被项目配置直接使用。
示例如下
android {
+ namespace = gropify.project.namespace
+ compileSdk = gropify.project.compileSdk
+
+ defaultConfig {
+ minSdk = gropify.project.minSdk
+ targetSdk = gropify.project.targetSdk
+ }
+}
+当你设置了 manifestPlaceholders = true 时，Gropify 将自动将这些属性键值同步到 android 配置方法块中的 manifestPlaceholders。
此时你可以直接在 AndroidManifest.xml 中使用这些占位符。
示例如下
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+ <application
+ android:label="${project.appName}"
+ android:icon="@mipmap/ic_launcher">
+
+ ...
+ </application>
+</manifest>
+你可以无需再使用 buildConfigField 向 BuildConfig 添加代码，有了 Gropify 生成的属性键值代码，你可以更加灵活地管理你的项目。
你还可以在属性键值中使用插值 ${...} 互相引用其中的内容，但不允许递归引用。
当你设置了 useValueInterpolation = true 时，Gropify 将自动合并这些引用的内容到对应位置。
示例如下
project.name=MyDemo
+project.developer.name=myname
+project.url=https://github.com/${project.developer.name}/${project.name}
+如果你在 locations 中添加了 GropifyLocation.SystemEnv，你还可以直接引用系统环境变量。
示例如下
# Linux 或 macOS 系统中使用 $USER 环境变量可以获取当前用户名
+project.developer.name=${USER}
+# 假设你有一个名为 SECRET_KEY 的系统环境变量 (请确保安全)
+project.secretKey=${SECRET_KEY}
+注意
这个特性是 Gropify 提供的，原生的 gradle.properties 并不支持此功能。
插值内容通过 locations 的层级自上而下进行查找替换，如果存在重复的键值名称，将使用最后查找到的内容进行替换。
可能遇到的问题
如果你的项目仅存在一个根项目，且没有导入任何子项目，此时如果扩展方法不能正常生成， 你可以将你的根项目迁移至子项目并在 settings.gradle.kts 中导入这个子项目，这样即可解决此问题。
我们一般推荐将项目的功能进行分类，根项目仅用来管理插件和一些配置。
局限性说明
Gropify 无法生成 settings.gradle.kts 中的扩展方法，因为这属于 Gropify 的上游。