HighCapable/Gropify
5
0
Fork 0
mirror of https://github.com/HighCapable/Gropify.git synced 2025-12-11 15:53:54 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
fankesyooni
2025-11-11 16:16:56 +08:00
commit 45c7ca94e9
94 changed files with 9808 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs-source/.gitignore vendored Normal file
View File

@@ -0,0 +1,4 @@
/node_modules
/src/.vuepress/.cache
/src/.vuepress/.temp
/dist

3
docs-source/.vscode/settings.json vendored Normal file
View File

@@ -0,0 +1,3 @@
{
"git.ignoreLimitWarning": true
}

17
docs-source/package.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "gropify_docs",
"license": "Apache-2.0",
"devDependencies": {
"@mr-hope/vuepress-plugin-copy-code": "^1.30.0",
"@vuepress/plugin-prismjs": "2.0.0-rc.0",
"@vuepress/plugin-search": "2.0.0-rc.0",
"@vuepress/plugin-shiki": "2.0.0-rc.0",
"vuepress": "2.0.0-rc.0"
},
"scripts": {
"docs:dev": "vuepress dev src",
"docs:build": "vuepress build src",
"docs:build-gh-pages": "vuepress build src && touch dist/.nojekyll"
},
"dependencies": {}
}

64
docs-source/src/.vuepress/config.ts Normal file
View File

@@ -0,0 +1,64 @@
import { defaultTheme } from 'vuepress';
import { shikiPlugin } from '@vuepress/plugin-shiki';
import { searchPlugin } from '@vuepress/plugin-search';
import { navBarItems, sideBarItems, configs, pageLinkRefs } from './configs/template';
import { env, markdown } from './configs/utils';
export default {
dest: configs.dev.dest,
port: configs.dev.port,
base: configs.website.base,
head: [['link', { rel: 'icon', href: configs.website.icon }]],
title: configs.website.title,
description: configs.website.locales['/en/'].description,
locales: configs.website.locales,
theme: defaultTheme({
logo: configs.website.logo,
repo: configs.github.repo,
docsRepo: configs.github.repo,
docsBranch: configs.github.branch,
docsDir: configs.github.dir,
editLinkPattern: ':repo/edit/:branch/:path',
sidebar: sideBarItems,
sidebarDepth: 2,
locales: {
'/en/': {
navbar: navBarItems['/en/'],
selectLanguageText: 'English (US)',
selectLanguageName: 'English',
editLinkText: 'Edit this page on GitHub',
tip: 'Tips',
warning: 'Notice',
danger: 'Pay Attention',
},
'/zh-cn/': {
navbar: navBarItems['/zh-cn/'],
selectLanguageText: '简体中文 (CN)',
selectLanguageName: '简体中文',
editLinkText: '在 GitHub 上编辑此页',
notFound: ['这里什么都没有', '我们怎么到这来了？', '这是一个 404 页面', '看起来我们进入了错误的链接'],
backToHome: '回到首页',
contributorsText: '贡献者',
lastUpdatedText: '上次更新',
tip: '小提示',
warning: '注意',
danger: '特别注意',
openInNewWindow: '在新窗口中打开',
toggleColorMode: '切换颜色模式'
}
},
}),
extendsMarkdown: (md: markdownit) => {
markdown.injectLinks(md, env.dev ? pageLinkRefs.dev : pageLinkRefs.prod);
},
plugins: [
shikiPlugin({ theme: 'github-dark-dimmed' }),
searchPlugin({
isSearchable: (page) => page.path !== '/',
locales: {
'/en/': { placeholder: 'Search' },
'/zh-cn/': { placeholder: '搜索' }
}
})
]
};

107
docs-source/src/.vuepress/configs/template.ts Normal file
View File

@@ -0,0 +1,107 @@
import { i18n } from './utils';
interface PageLinkRefs {
dev: Record<string, string>[];
prod: Record<string, string>[];
}
const navigationLinks = {
start: [
'/guide/home',
'/guide/quick-start'
],
about: [
'/about/changelog',
'/about/future',
'/about/contacts',
'/about/about'
]
};
export const configs = {
dev: {
dest: 'dist',
port: 9000
},
website: {
base: '/Gropify/',
icon: '/Gropify/images/logo.svg',
logo: '/images/logo.svg',
title: 'Gropify',
locales: {
'/en/': {
lang: 'en-US',
description: 'A type-safe and modern properties plugin for Gradle'
},
'/zh-cn/': {
lang: 'zh-CN',
description: '一个类型安全且现代化的 Gradle 属性插件'
}
}
},
github: {
repo: 'https://github.com/HighCapable/Gropify',
page: 'https://highcapable.github.io/Gropify',
branch: 'main',
dir: 'docs-source/src'
}
};
export const pageLinkRefs: PageLinkRefs = {
dev: [
{ 'repo://': `${configs.github.repo}/` }
],
prod: [
{ 'repo://': `${configs.github.repo}/` }
]
};
export const navBarItems = {
'/en/': [{
text: 'Navigation',
children: [{
text: 'Get Started',
children: i18n.array(navigationLinks.start, 'en')
}, {
text: 'About',
children: i18n.array(navigationLinks.about, 'en')
}]
}, {
text: 'Contact Us',
link: i18n.string(navigationLinks.about[2], 'en')
}],
'/zh-cn/': [{
text: '导航',
children: [{
text: '入门',
children: i18n.array(navigationLinks.start, 'zh-cn')
}, {
text: '关于',
children: i18n.array(navigationLinks.about, 'zh-cn')
}]
}, {
text: '联系我们',
link: i18n.string(navigationLinks.about[2], 'zh-cn')
}]
};
export const sideBarItems = {
'/en/': [{
text: 'Get Started',
collapsible: true,
children: i18n.array(navigationLinks.start, 'en')
}, {
text: 'About',
collapsible: true,
children: i18n.array(navigationLinks.about, 'en')
}],
'/zh-cn/': [{
text: '入门',
collapsible: true,
children: i18n.array(navigationLinks.start, 'zh-cn')
}, {
text: '关于',
collapsible: true,
children: i18n.array(navigationLinks.about, 'zh-cn')
}]
};

39
docs-source/src/.vuepress/configs/utils.ts Normal file
View File

@@ -0,0 +1,39 @@
export const env = {
dev: process.env.NODE_ENV === 'development'
};
export const i18n = {
space: ' ',
string: (content: string, locale: string) => {
return '/' + locale + content;
},
array: (contents: string[], locale: string) => {
const newContents: string[] = [];
contents.forEach((content) => {
newContents.push(i18n.string(content, locale));
});
return newContents;
}
};
export const markdown = {
injectLinks: (md: markdownit, maps: Record<string, string>[]) => {
const defaultRender = md.renderer.rules.link_open || function (tokens, idx, options, _env, self) {
return self.renderToken(tokens, idx, options);
};
md.renderer.rules.link_open = function (tokens, idx, options, env, self) {
const hrefIndex = tokens[idx].attrIndex('href');
let current = tokens[idx].attrs!![hrefIndex][1];
for (const map of maps) {
for (const [search, replace] of Object.entries(map)) {
if (current.startsWith(search)) {
current = current.replace(search, replace);
tokens[idx].attrs!![hrefIndex][1] = current;
break;
}
}
}
return defaultRender(tokens, idx, options, env, self);
};
}
};

16
docs-source/src/.vuepress/public/images/logo.svg Normal file
View File

@@ -0,0 +1,16 @@
<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="512" height="512" rx="128" fill="#434256"/>
<path d="M165.49 165.49C215.477 115.503 296.523 115.503 346.51 165.49C396.497 215.477 396.497 296.523 346.51 346.51C334.685 358.335 321.121 367.362 306.642 373.592C303.452 374.965 299.999 372.555 299.999 369.082V339.791C299.999 337.961 301.005 336.286 302.583 335.358C309.178 331.482 315.393 326.714 321.054 321.054C356.982 285.126 356.982 226.874 321.054 190.946C285.126 155.018 226.874 155.018 190.946 190.946C155.018 226.874 155.018 285.126 190.946 321.054C196.607 326.714 202.821 331.482 209.415 335.358C210.993 336.286 211.999 337.961 211.999 339.791V369.082C211.999 372.555 208.546 374.964 205.356 373.592C190.878 367.362 177.315 358.334 165.49 346.51C115.503 296.523 115.503 215.477 165.49 165.49Z" fill="white"/>
<path d="M235.361 102.5H276.639C280.539 102.5 283.789 105.49 284.113 109.377L286.779 141.377C287.144 145.75 283.693 149.5 279.306 149.5H232.694C228.307 149.5 224.856 145.75 225.221 141.377L227.887 109.377C228.211 105.49 231.461 102.5 235.361 102.5Z" fill="white" stroke="white"/>
<path d="M133.661 163.046L163.046 133.661C165.765 130.942 170.101 130.72 173.084 133.147L191.006 147.735C194.453 150.541 194.719 155.712 191.576 158.855L158.854 191.576C155.712 194.719 150.541 194.454 147.735 191.006L133.147 173.084C130.72 170.101 130.942 165.765 133.661 163.046Z" fill="white" stroke="white"/>
<path d="M378.339 163.046L348.954 133.661C346.235 130.942 341.899 130.72 338.916 133.147L320.994 147.735C317.547 150.541 317.281 155.712 320.424 158.855L353.146 191.576C356.288 194.719 361.459 194.454 364.265 191.006L378.853 173.084C381.28 170.101 381.058 165.765 378.339 163.046Z" fill="white" stroke="white"/>
<path d="M133.659 348.96L163.044 378.345C165.763 381.064 170.098 381.286 173.081 378.859L191.004 364.271C194.451 361.465 194.716 356.294 191.574 353.151L158.852 320.43C155.709 317.287 150.538 317.552 147.732 321L133.145 338.922C130.717 341.905 130.939 346.241 133.659 348.96Z" fill="white" stroke="white"/>
<path d="M378.336 348.96L348.951 378.345C346.231 381.064 341.896 381.286 338.913 378.858L320.989 364.27C317.542 361.464 317.277 356.293 320.42 353.15L353.141 320.429C356.284 317.286 361.455 317.551 364.261 320.998L378.849 338.922C381.277 341.905 381.055 346.24 378.336 348.96Z" fill="white" stroke="white"/>
<path d="M409.5 235.361V276.639C409.5 280.539 406.51 283.789 402.623 284.113L370.623 286.779C366.25 287.144 362.5 283.693 362.5 279.306V232.694C362.5 228.307 366.25 224.856 370.623 225.221L402.623 227.887C406.51 228.211 409.5 231.461 409.5 235.361Z" fill="white" stroke="white"/>
<path d="M102.5 276.639V235.361C102.5 231.461 105.49 228.211 109.377 227.887L141.377 225.221C145.75 224.856 149.5 228.307 149.5 232.694V279.306C149.5 283.693 145.75 287.144 141.377 286.779L109.377 284.113C105.49 283.789 102.5 280.539 102.5 276.639Z" fill="white" stroke="white"/>
<path opacity="0.6" d="M280.3 398C280.3 401.727 280.3 403.591 279.691 405.062C278.879 407.022 277.322 408.579 275.361 409.391C273.891 410 272.027 410 268.3 410H243.7C239.973 410 238.109 410 236.639 409.391C234.678 408.579 233.121 407.022 232.309 405.062C231.7 403.591 231.7 401.727 231.7 398H280.3Z" fill="white"/>
<path d="M280.3 398H231.7V263.391C236.076 267.895 245.313 271 256 271C266.687 271 275.924 267.895 280.3 263.391V398Z" fill="white"/>
<path opacity="0.8" d="M276.976 249C278.273 249.8 279.391 250.674 280.3 251.61V263.39C275.924 267.894 266.688 271 256 271C245.313 271 236.076 267.895 231.7 263.391V251.609C232.609 250.674 233.727 249.799 235.023 249H276.976Z" fill="white"/>
<path d="M243.315 225.463C246.767 228.298 251.185 230.001 256 230.001C260.815 230.001 265.233 228.298 268.685 225.464L277.42 244.375C279.513 248.906 280.559 251.173 280.248 253.006C280.077 254.011 279.653 254.945 279.031 255.729C278.789 256.126 278.504 256.518 278.173 256.901C276.967 258.296 275.199 259.564 272.971 260.632C270.742 261.7 268.095 262.547 265.184 263.125C262.272 263.703 259.151 264 256 264C252.848 264 249.727 263.703 246.815 263.125C243.904 262.547 241.258 261.7 239.029 260.632C236.801 259.564 235.032 258.296 233.826 256.901C233.495 256.518 233.209 256.125 232.967 255.728C232.345 254.945 231.923 254.01 231.752 253.006C231.441 251.173 232.487 248.906 234.58 244.375L243.315 225.463Z" fill="white"/>
<path opacity="0.6" d="M253.361 206.92C255.026 206.105 256.972 206.106 258.637 206.92C260.552 207.858 261.94 210.861 264.715 216.868L268.684 225.462C265.232 228.297 260.815 229.999 256 229.999C251.184 229.999 246.766 228.297 243.314 225.461L247.284 216.868C250.059 210.861 251.446 207.858 253.361 206.92Z" fill="white"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

179
docs-source/src/.vuepress/styles/index.scss Normal file
View File

@@ -0,0 +1,179 @@
$primary-color: rgb(98, 95, 124);
$accent-color: rgb(145, 132, 151);
$content-width: 965px;
$scroll-bar-width: 8px;
$scroll-bar-height: 6.5px;
$scroll-bar-border-radius: 50px;
$scroll-bar-track-color-code: rgb(98, 95, 124);
$scroll-bar-thumb-hover-color-code: rgb(145, 132, 151);
:root {
--c-brand: #{$primary-color};
--c-brand-light: #{$accent-color};
--content-width: #{$content-width};
}
code {
padding: 3px 5px 3px 5px;
border-radius: 5px;
}
.badge {
margin-bottom: 5px;
}
.custom-container {
border-radius: 5px;
}
.sidebar-item {
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.language-text {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-kotlin {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-java {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-groovy {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-xml {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.hidden-anchor-page {
h6 {
color: transparent;
margin-bottom: -35px;
padding-top: 50px;
}
}
.code-page {
h1 {
font-size: 24pt;
}
h2 {
font-size: 18pt;
}
h3 {
font-size: 15pt;
}
h4 {
font-size: 12pt;
}
h5 {
font-size: 9.6pt;
}
h6 {
font-size: 8.4pt;
}
.symbol {
color: rgb(142, 155, 168);
}
.deprecated {
color: rgb(142, 155, 168);
text-decoration: line-through;
}
}
html {
scroll-behavior: smooth;
::-webkit-scrollbar {
width: #{$scroll-bar-width};
height: #{$scroll-bar-height};
}
::-webkit-scrollbar-track {
background: rgb(234, 236, 239);
}
::-webkit-scrollbar-thumb {
background: rgb(189, 189, 189);
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: rgb(133, 133, 133);
border-radius: #{$scroll-bar-border-radius};
}
}
html.dark {
--c-brand: #{$primary-color};
--c-brand-light: #{$accent-color};
--content-width: #{$content-width};
::-webkit-scrollbar {
width: #{$scroll-bar-width};
height: #{$scroll-bar-height};
}
::-webkit-scrollbar-track {
background: rgb(41, 46, 53);
}
::-webkit-scrollbar-thumb {
background: rgb(65, 72, 83);
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: rgb(56, 62, 72);
border-radius: #{$scroll-bar-border-radius};
}
}

27
docs-source/src/en/about/about.md Normal file
View File

@@ -0,0 +1,27 @@
# About This Document
> This document is powered by [VuePress](https://v2.vuepress.vuejs.org/en).
## License
[Apache-2.0](https://github.com/HighCapable/Gropify/blob/main/LICENSE)
```:no-line-numbers
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

21
docs-source/src/en/about/changelog.md Normal file
View File

@@ -0,0 +1,21 @@
# Changelog
> The version update history of `Gropify` is recorded here.
::: danger
We will only maintain the latest API version. If you are using an outdated API version, you voluntarily renounce any possibility of maintenance.
:::
::: warning
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.0 | 2025.11.11 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven

15
docs-source/src/en/about/contacts.md Normal file
View File

@@ -0,0 +1,15 @@
# Contact Us
> If you have any questions during usage, or have any constructive suggestions, you can contact us.
Join our developers group.
- [Click to join Telegram group (Developer)](https://t.me/HighCapable_Dev)
Find me on **Twitter** [@fankesyooni](https://twitter.com/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.

12
docs-source/src/en/about/future.md Normal file
View File

@@ -0,0 +1,12 @@
# 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 `Gropify` may 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.

71
docs-source/src/en/guide/home.md Normal file
View File

@@ -0,0 +1,71 @@
# Introduction
> `Gropify` is 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](https://github.com/Lagrio). The name comes from **G**radleP**ropify**, meaning a plugin for Gradle properties.
It is a brand-new project rebuilt from [SweetProperty](https://github.com/HighCapable/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
```properties
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)
```kotlin
val appName = gropify.project.app.name
val appVersion = gropify.project.app.version
```
```groovy
def appName = gropify.project.app.name
def appVersion = gropify.project.app.version
```
> Source Code (Kotlin, Java)
```kotlin
val appName = MyAppProperties.PROJECT_APP_NAME
val appVersion = MyAppProperties.PROJECT_APP_VERSION
```
```java
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](repo://issues)
to make suggestions to us.

691
docs-source/src/en/guide/quick-start.md Normal file
View File

@@ -0,0 +1,691 @@
# Quick Start
> Integrate `Gropify` into your project.
## Deploy Plugin
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.gropify/gropify-gradle-plugin?logo=apachemaven&logoColor=orange&style=flat-square)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fgropify%2Fgropify-gradle-plugin%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases&style=flat-square)
`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
```kotlin
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
```kotlin
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.
::: warning
`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
```kotlin
gropify {
// Enable Gropify, setting it to `false` will disable all features
isEnabled = true
}
```
`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
```kotlin
// 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](#build-script-configuration), [Android Project Configuration](#android-project-configuration), [JVM Project Configuration](#jvm-project-configuration), [Kotlin Multiplatform Project Configuration](#kotlin-multiplatform-project-configuration).
> The following example
```kotlin
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" }
)
// 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)
}
```
::: tip
When referencing `GropifyLocation`, the build script may generate the following at the top of the build script when used with IDE auto-import.
```kotlin :no-line-numbers
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
```kotlin
buildscript {
// Custom buildscript extension name.
//
// Default is "gropify".
extensionName = "gropify"
}
```
::: warning
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
```kotlin
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
}
```
### 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](#android-project-configuration) for configuration.
The configuration here includes the configuration in `common`, and you can override it.
> The following example
```kotlin
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
```kotlin
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
```properties
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
```kotlin
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
```kotlin
val groupName = GropifyDemoProperties.PROJECT_GROUP_NAME
val description = GropifyDemoProperties.PROJECT_DESCRIPTION
val version = GropifyDemoProperties.PROJECT_VERSION
```
> Java
```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
```properties
project.namespace=com.highcapable.gropifydemo
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
```kotlin
android {
namespace = gropify.project.namespace
compileSdk = gropify.project.compileSdk
defaultConfig {
minSdk = gropify.project.minSdk
targetSdk = gropify.project.targetSdk
}
}
```
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
```properties
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
```properties
# 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}
```
::: warning
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`.

13
docs-source/src/en/index.md Normal file
View File

@@ -0,0 +1,13 @@
---
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
---

17
docs-source/src/index.md Normal file
View File

@@ -0,0 +1,17 @@
---
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
---

27
docs-source/src/zh-cn/about/about.md Normal file
View File

@@ -0,0 +1,27 @@
# 关于此文档
> 此文档由 [VuePress](https://v2.vuepress.vuejs.org/zh) 强力驱动。
## 许可证
[Apache-2.0](https://github.com/HighCapable/Gropify/blob/main/LICENSE)
```:no-line-numbers
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

13
docs-source/src/zh-cn/about/changelog.md Normal file
View File

@@ -0,0 +1,13 @@
# 更新日志
> 这里记录了 `Gropify` 的版本更新历史。
::: danger
我们只会对最新的 API 版本进行维护，若你正在使用过时的 API 版本则代表你自愿放弃一切维护的可能性。
:::
### 1.0.0 | 2025.11.11 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven

14
docs-source/src/zh-cn/about/contacts.md Normal file
View File

@@ -0,0 +1,14 @@
# 联系我们
> 如在使用中有任何问题，或有任何建设性的建议，都可以联系我们。
加入我们的开发者群组。
- [点击加入 Telegram 群组 (开发者)](https://t.me/HighCapable_Dev)
- [点击加入 QQ 群 (开发者)](https://qm.qq.com/cgi-bin/qm/qr?k=Pnsc5RY6N2mBKFjOLPiYldbAbprAU3V7&jump_from=webapi&authKey=X5EsOVzLXt1dRunge8ryTxDRrh9/IiW1Pua75eDLh9RE3KXE+bwXIYF5cWri/9lf)
在 **酷安** 找到我 [@星夜不荟](http://www.coolapk.com/u/876977)。
## 助力维护
感谢您选择并使用 `Gropify`，如有代码相关的建议和请求，可在 GitHub 提交 Pull Request。

11
docs-source/src/zh-cn/about/future.md Normal file
View File

@@ -0,0 +1,11 @@
# 展望未来
> 未来是美好的，也是不确定的，让我们共同期待 `Gropify` 在未来的发展空间。
## 未来的计划
> 这里收录了 `Gropify` 可能会在后期添加的功能。
### 支持更多项目类型
`Gropify` 目前支持将属性生成到 Kotlin、Java 和 Android 项目的源代码中，在未来可能会支持更多能够参与 Gradle 构建的项目，例如 C/C++ (Android JNI)、Swift 等，以满足更多开发者的需求。

67
docs-source/src/zh-cn/guide/home.md Normal file
View File

@@ -0,0 +1,67 @@
# 介绍
> `Gropify` 是一个类型安全且现代化的 Gradle 属性插件。
## 背景
这是一个为 Gradle 构建脚本设计的插件，旨在将类似 `gradle.properties` 文件中的属性以类型安全的方式引入到构建脚本中，从而避免硬编码字符串可能带来的问题。
项目图标由 [MaiTungTM](https://github.com/Lagrio) 设计，名称取自 **G**radleP**ropify**，意为针对 Gradle 属性的插件。
它是基于 [SweetProperty](https://github.com/HighCapable/SweetProperty) 重构的全新项目，借鉴了以往的设计方案，使得其在原有基础上更加完善和易用。
`Gropify` 的配置方案与 `SweetProperty` 类似，如果你正在使用 `SweetProperty`，你可以考虑将其迁移到 `Gropify`。
## 用途
`Gropify` 主要针对 Kotlin DSL 构建脚本设计，Groovy 语言可以直接将 `gradle.properties` 文件中的属性作为变量使用，但是你也可以通过 `Gropify` 来实现类型安全的属性访问。
`Gropify` 同时支持将类似 `gradle.properties` 文件中的属性以类型安全的方式生成到 Kotlin、Java、Android 项目的源码中以供应用程序运行时使用，功能类似 Android 的 `BuildConfig` 中的 `buildConfigField` 功能。
假设我们有以下 `gradle.properties` 文件。
> 示例如下
```properties
project.app.name=Gropify-Demo
project.app.version=1.0.0
```
这是 `Gropify` 自动生成的代码调用示例。
> 构建脚本 (Kotlin DSL、Groovy DSL)
```kotlin
val appName = gropify.project.app.name
val appVersion = gropify.project.app.version
```
```groovy
def appName = gropify.project.app.name
def appVersion = gropify.project.app.version
```
> 源代码 (Kotlin、Java)
```kotlin
val appName = MyAppProperties.PROJECT_APP_NAME
val appVersion = MyAppProperties.PROJECT_APP_VERSION
```
```java
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](repo://issues) 向我们提出建议。

661
docs-source/src/zh-cn/guide/quick-start.md Normal file
View File

@@ -0,0 +1,661 @@
# 快速开始
> 集成 `Gropify` 到你的项目中。
## 部署插件
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.gropify/gropify-gradle-plugin?logo=apachemaven&logoColor=orange&style=flat-square)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fgropify%2Fgropify-gradle-plugin%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases&style=flat-square)
`Gropify` 的依赖发布在 **Maven Central** 和我们的公共存储库中，你可以使用如下方式配置存储库。
我们建议使用不低于 `7.x.x` 版本的 Gradle，并推荐使用 Kotlin DSL 作为 Gradle 构建脚本语言，文档中将不再详细介绍在 Groovy DSL 中的使用方法。
我们推荐使用 `pluginManagement` 新方式进行部署，它是自 Gradle `7.x.x` 版本开始添加的功能。
如果你的项目依然在使用 `buildscript` 的方式进行管理，推荐迁移到新方式，这里将不再提供旧版本的使用方式说明。
首先，在你的项目 `settings.gradle.kts` 中配置插件的存储库。
> 示例如下
```kotlin
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`。
> 示例如下
```kotlin
plugins {
id("com.highcapable.gropify") version "<version>"
}
```
请将 `<version>` 修改为此小结顶部显示的版本。
上述配置完成后，运行一次 Gradle Sync。
`Gropify` 将会自动搜索根项目和每个子项目中的 `gradle.properties` 文件，并读取其中的属性键值，为每个项目生成对应的代码。
::: warning
`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`。
> 示例如下
```kotlin
gropify {
// 启用 Gropify，设置为 `false` 将禁用所有功能
isEnabled = true
}
```
`Gropify` 的配置模式分为 `global` 全局配置和 `rootProject`、`projects` 根项目和子项目配置三种。
你可以在子项的代码块中继续配置和集成顶层项目的配置。
以下配置均在 `gropify` 方法块中进行。
> 示例如下
```kotlin
// 全局配置
//
// 你可以在全局配置中修改所有项目中的配置
// 每个项目中未进行声明的配置将使用全局配置
// 每个配置方法块中的功能完全一致
//
// 你可以参考下方根项目、子项目的配置方法
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 项目配置](#android-项目配置)、[JVM 项目配置](#jvm-项目配置)、[Kotlin 多平台项目配置](#kotlin-多平台项目配置) 中。
> 示例如下
```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" }
)
// 设置查找属性键值的位置
//
// 默认为 [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)
}
```
::: tip
在引用 `GropifyLocation` 时，构建脚本在配合 IDE 自动导入时可能会在构建脚本顶部生成以下内容。
```kotlin :no-line-numbers
import com.highcapable.gropify.plugin.config.type.GropifyLocation
```
`Gropify` 对此做了 alias 处理，你可以直接删除此 import 语句。
:::
### 构建脚本配置
在构建脚本中生成的代码可直接被当前 `build.gradle.kts`、`build.gradle` 使用。
这里的配置包括 `common` 中的配置，你可以对其进行复写。
> 示例如下
```kotlin
buildscript {
// 自定义构建脚本扩展名称
//
// 默认为 "gropify"
extensionName = "gropify"
}
```
::: warning
Gradle 中也有一个 `buildscript` 方法块，请注意使用正确的 DSL 层级。
:::
### Android 项目配置
此配置块中的内容仅对存在 AGP 的项目生效。
这里的配置包括 `common` 中的配置，你可以对其进行复写。
> 示例如下
```kotlin
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
}
```
### JVM 项目配置
此配置块中的内容仅对纯 JVM 项目生效 (包括 Kotlin、Java 项目)，如果是 Android 项目请参考 [Android 项目配置](#android-项目配置) 进行配置。
这里的配置包括 `common` 中的配置，你可以对其进行复写。
> 示例如下
```kotlin
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` 中的配置，你可以对其进行复写。
```kotlin
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` 配置文件。
> 示例如下
```properties
project.groupName=com.highcapable.gropifydemo
project.description=Hello Gropify Demo!
project.version=1.0.0
```
在构建脚本 `build.gradle.kts` 中，我们就可以如下所示这样直接去使用这些键值。
这里以 Maven 发布的配置部分举例。
> 示例如下
```kotlin
publications {
create<MavenPublication>("maven") {
groupId = gropify.project.groupName
version = gropify.project.version
pom.description.set(gropify.project.description)
from(components["java"])
}
}
```
同样地，你也可以在当前项目中调用生成的键值。
> Kotlin
```kotlin
val groupName = GropifyDemoProperties.PROJECT_GROUP_NAME
val description = GropifyDemoProperties.PROJECT_DESCRIPTION
val version = GropifyDemoProperties.PROJECT_VERSION
```
> Java
```java
var groupName = GropifyDemoProperties.PROJECT_GROUP_NAME;
var description = GropifyDemoProperties.PROJECT_DESCRIPTION;
var version = GropifyDemoProperties.PROJECT_VERSION;
```
下面再以 Android 项目举例。
在 Android 项目中通常需要配置很多重复、固定的属性，例如 `targetSdk`。
> 示例如下
```properties
project.namespace=com.highcapable.gropifydemo
project.compileSdk=36
project.targetSdk=36
project.minSdk=26
```
当你设置了 `useTypeAutoConversion = true` 时，`Gropify` 在生成实体类过程在默认配置下将尝试将其转换为对应的类型。
例如下方所使用的键值，其类型可被识别为字符串和整型，可被项目配置直接使用。
> 示例如下
```kotlin
android {
namespace = gropify.project.namespace
compileSdk = gropify.project.compileSdk
defaultConfig {
minSdk = gropify.project.minSdk
targetSdk = gropify.project.targetSdk
}
}
```
你可以无需再使用 `buildConfigField` 向 `BuildConfig` 添加代码，有了 `Gropify` 生成的属性键值代码，你可以更加灵活地管理你的项目。
你还可以在属性键值中使用插值 `${...}` 互相引用其中的内容，但不允许递归引用。
当你设置了 `useValueInterpolation = true` 时，`Gropify` 将自动合并这些引用的内容到对应位置。
> 示例如下
```properties
project.name=MyDemo
project.developer.name=myname
project.url=https://github.com/${project.developer.name}/${project.name}
```
如果你在 `locations` 中添加了 `GropifyLocation.SystemEnv`，你还可以直接引用系统环境变量。
> 示例如下
```properties
# Linux 或 macOS 系统中使用 $USER 环境变量可以获取当前用户名
project.developer.name=${USER}
# 假设你有一个名为 SECRET_KEY 的系统环境变量 (请确保安全)
project.secretKey=${SECRET_KEY}
```
::: warning
这个特性是 `Gropify` 提供的，原生的 `gradle.properties` 并不支持此功能。
插值内容通过 `locations` 的层级自上而下进行查找替换，如果存在重复的键值名称，将使用最后查找到的内容进行替换。
:::
## 可能遇到的问题
如果你的项目仅存在一个根项目，且没有导入任何子项目，此时如果扩展方法不能正常生成，
你可以将你的根项目迁移至子项目并在 `settings.gradle.kts` 中导入这个子项目，这样即可解决此问题。
我们一般推荐将项目的功能进行分类，根项目仅用来管理插件和一些配置。
## 局限性说明
`Gropify` 无法生成 `settings.gradle.kts` 中的扩展方法，因为这属于 `Gropify` 的上游。

13
docs-source/src/zh-cn/index.md Normal file
View File

@@ -0,0 +1,13 @@
---
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
---

2004
docs-source/yarn.lock Normal file
View File

File diff suppressed because it is too large Load Diff