├── .devcontainer ├── Dockerfile ├── LICENSE.txt ├── devcontainer.json └── requirements.txt ├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── 1-report-issue.yml │ ├── 2-new-recipe.yml │ ├── 3-new-chapter.yml │ ├── 4-other.yml │ └── config.yml ├── dependabot.yml ├── release-drafter.yml └── workflows │ ├── changelog.yml │ ├── ci.yml │ ├── deploy.yml │ ├── preview-cleanup.yml │ └── release.yml ├── .gitignore ├── .vscode ├── settings.json └── tasks.json ├── LICENSE.txt ├── README.md ├── docs ├── CONTRIBUTING.md ├── android │ ├── README.md │ ├── optimization.md │ └── troubleshooting.md ├── assets │ ├── css │ │ └── gradle.css │ └── images │ │ └── logos │ │ ├── gradle-build-tool.svg │ │ └── gradle.svg ├── chapters.md ├── ci │ ├── README.md │ ├── github-actions.md │ ├── gitlab-ci.md │ ├── images │ │ ├── github-actions-cache-details.png │ │ ├── github-actions-create-repository.png │ │ ├── github-actions-dependency-alerts.png │ │ ├── github-actions-dependency-graph.png │ │ ├── github-actions-job-details.png │ │ ├── github-actions-workflow.png │ │ ├── github-actions-workflows.png │ │ ├── gitlab-ci-create-repository.png │ │ ├── jenkins-build-scan.png │ │ ├── jenkins-build-step.png │ │ ├── jenkins-scm.png │ │ ├── teamcity-build-scan-plugin.png │ │ ├── teamcity-build-step.png │ │ ├── teamcity-create-project.png │ │ ├── teamcity-log-link.png │ │ ├── teamcity-results.png │ │ ├── teamcity-scan.png │ │ ├── teamcity-step-added.png │ │ ├── teamcity-step-upd.png │ │ ├── teamcity-tests.png │ │ └── travis-enable-project.png │ ├── jenkins.md │ ├── teamcity.md │ └── travis-ci.md ├── cookie-test.md ├── index.md ├── integrations │ ├── README.md │ └── maven-central │ │ └── publishing.md ├── kotlin │ └── README.md ├── plugin-development │ ├── README.md │ ├── configuration-cache │ │ └── README.md │ └── kotlin-plugins.md ├── preface.md └── troubleshooting │ └── README.md ├── mkdocs.yml └── overrides ├── home.html ├── main.html └── partials └── integrations └── analytics └── custom.html /.devcontainer/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:3.10.4-slim-buster 2 | 3 | RUN apt-get update 4 | RUN apt-get install -y libsass-dev build-essential libcairo2 git libpango-1.0-0 libpangoft2-1.0-0 pangocairo-1.0 5 | -------------------------------------------------------------------------------- /.devcontainer/LICENSE.txt: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020-2024 Kento Shimada, Oleg Nenashev, and other contributors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | // Credits - https://github.com/hitsumabushi845/MkDocs-with-Remote-Containers 2 | { 3 | "name": "Material for MkDocs", 4 | "dockerFile": "Dockerfile", 5 | "customizations": { 6 | "vscode": { 7 | // Set *default* container specific settings.json values on container create. 8 | "settings": { 9 | "terminal.integrated.shell.linux": "/bin/bash", 10 | "debug.javascript.usePreview": false 11 | }, 12 | // Add the IDs of extensions you want installed when the container is created. 13 | "extensions": [ 14 | "yzhang.markdown-all-in-one", 15 | "redhat.vscode-yaml", 16 | "shardulm94.trailing-spaces", 17 | "oderwat.indent-rainbow", 18 | "msjsdiag.debugger-for-chrome" 19 | ], 20 | }, 21 | }, 22 | // Use 'forwardPorts' to make a list of ports inside the container available locally. 23 | "forwardPorts": [ 24 | 8000 25 | ], 26 | // Use 'postCreateCommand' to run commands after the container is created. 27 | "postCreateCommand": "pip3 install -r .devcontainer/requirements.txt " 28 | // Uncomment to connect as a non-root user. See https://aka.ms/vscode-remote/containers/non-root. 29 | //"remoteUser": "vscode" 30 | } 31 | -------------------------------------------------------------------------------- /.devcontainer/requirements.txt: -------------------------------------------------------------------------------- 1 | Markdown==3.5 2 | MarkupSafe==2.1.3 3 | mergedeep==1.3.4 4 | mkdocs==1.6.1 5 | mkdocs-autorefs==0.5.0 6 | mkdocs-git-committers-plugin-2==2.4.1 7 | mkdocs-git-revision-date-localized-plugin==1.2.9 8 | mkdocs-macros-plugin==1.0.5 9 | mkdocs-material==9.6.14 10 | mkdocs-material[imaging]==9.6.14 11 | mkdocs-multirepo-plugin==0.6.3 12 | mkdocs-nav-weight==0.2.0 13 | mkdocs-redirects==1.2.1 14 | mkdocs-extra-sass-plugin==0.1.0 15 | mkdocs-render-swagger-plugin==0.1.1 16 | mkdocs-pdf==0.1.1 17 | mkdocs-with-pdf==0.9.3 18 | livereload==2.6.3 19 | lxml==5.3.0 20 | click==8.1.7 21 | dacite==1.8.1 22 | ghp-import==2.1.0 23 | jinja2==3.1.2 24 | mypy-extensions==1.0.0 25 | packaging==23.2 26 | pathspec==0.11.2 27 | platformdirs==3.11.0 28 | python-dateutil==2.8.2 29 | python-slugify==8.0.1 30 | pypng==0.20220715.0 31 | pyyaml==6.0.1 32 | pyyaml-env-tag==0.1 33 | qrcode==7.4.2 34 | six==1.16.0 35 | text-unidecode==1.3 36 | typing-extensions==4.8.0 37 | typing-inspect==0.8.0 38 | watchdog==3.0.0 39 | weasyprint==52.5 40 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @gradle/bt-docs-reviewers 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/1-report-issue.yml: -------------------------------------------------------------------------------- 1 | name: '🐛 Bug report' 2 | labels: 'bug' 3 | description: > 4 | Create a bug report if you see something wrong with the pages 5 | 6 | body: 7 | 8 | - type: input 9 | attributes: 10 | label: Page URL 11 | description: URL of the page where you see the issue. 12 | validations: 13 | required: true 14 | 15 | - type: textarea 16 | attributes: 17 | label: Description 18 | description: Describe the issue and the expected changes 19 | validations: 20 | required: true 21 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/2-new-recipe.yml: -------------------------------------------------------------------------------- 1 | name: '📝 New Recipe or Use-case' 2 | labels: 'documentation' 3 | description: > 4 | Let us know if any documentation is missing or could be improved. 5 | Any use cases are welcome! 6 | 7 | body: 8 | - type: textarea 9 | attributes: 10 | label: Describe your use-case which is not covered by existing documentation. 11 | description: If it is easier to submit a documentation patch instead of writing an issue, just do it! 12 | validations: 13 | required: true 14 | 15 | - type: textarea 16 | attributes: 17 | label: Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration. 18 | 19 | 20 | 21 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/3-new-chapter.yml: -------------------------------------------------------------------------------- 1 | name: '📝 New Chapter' 2 | labels: 'documentation' 3 | description: > 4 | Want to propose a new section? 5 | 6 | body: 7 | - type: textarea 8 | attributes: 9 | label: Describe an area which is not yet covered by existing documentation. 10 | validations: 11 | required: true 12 | 13 | - type: textarea 14 | attributes: 15 | label: > 16 | Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration. 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/4-other.yml: -------------------------------------------------------------------------------- 1 | name: "❓ Other" 2 | description: Free form issue for everything that doesn't fit in the templates above 3 | body: 4 | - type: textarea 5 | attributes: 6 | label: Description 7 | value: | 8 | This is a place of freedom. Enjoy! 9 | validations: 10 | required: true 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: "🛟 Community Slack" 4 | url: https://community.gradle.org/contributing/community-slack/ 5 | about: > 6 | There is also #community-support channel if you need help. 7 | If you want to share feedback or discuss any changes in the docs, consider joining our the #docs channel. 8 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "weekly" 7 | -------------------------------------------------------------------------------- /.github/release-drafter.yml: -------------------------------------------------------------------------------- 1 | # Use https://github.com/gradle/.github/blob/main/.github/release_drafter.yml 2 | _extends: .github 3 | -------------------------------------------------------------------------------- /.github/workflows/changelog.yml: -------------------------------------------------------------------------------- 1 | name: Release Drafter 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | workflow_dispatch: 8 | 9 | jobs: 10 | update_release_draft: 11 | runs-on: ubuntu-latest 12 | 13 | permissions: 14 | # Write permission is required to create a github release 15 | contents: write 16 | # Write permission is required for autolabeler 17 | pull-requests: write 18 | 19 | steps: 20 | - uses: release-drafter/release-drafter@v6 21 | with: 22 | name: next 23 | tag: next 24 | version: next 25 | env: 26 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 27 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: Continuous Integration 2 | 3 | on: 4 | # We have deploy there 5 | # push: 6 | # branches: [ "main" ] 7 | pull_request: 8 | branches: [ "main" ] 9 | workflow_dispatch: 10 | 11 | jobs: 12 | # Build job 13 | build: 14 | runs-on: ubuntu-latest 15 | 16 | permissions: 17 | contents: write 18 | packages: read 19 | pull-requests: write 20 | 21 | env: 22 | PR_PATH: pull/${{github.event.number}} 23 | DOMAIN: gradle.github.io 24 | PREVIEW_REPO: community-site-preview 25 | 26 | steps: 27 | - name: Checkout 28 | uses: actions/checkout@v4 29 | with: 30 | submodules: "true" 31 | 32 | - name: Set up Python 33 | uses: actions/setup-python@v5 34 | with: 35 | python-version: "3.10" 36 | 37 | - name: Install dependencies 38 | run: pip install -r .devcontainer/requirements.txt 39 | 40 | - name: Build the docs 41 | run: mkdocs build 42 | 43 | - name: Deploy to PR preview 44 | uses: peaceiris/actions-gh-pages@v4 45 | if: github.ref != 'refs/heads/main' 46 | with: 47 | deploy_key: ${{ secrets.PREVIEW_DEPLOYMENT_KEY }} 48 | external_repository: gradle/${{ env.PREVIEW_REPO }} 49 | publish_dir: ./_site 50 | destination_dir: ${{ env.PR_PATH }} 51 | 52 | - name: Update comment 53 | uses: hasura/comment-progress@v2.3.0 54 | if: github.ref != 'refs/heads/main' 55 | with: 56 | github-token: ${{ secrets.GITHUB_TOKEN }} 57 | repository: ${{ github.repository }} 58 | number: ${{ github.event.number }} 59 | id: deploy-preview 60 | message: > 61 | A preview of ${{ github.event.after }} is uploaded and can be seen here: 62 | 63 | ✨ https://${{ env.DOMAIN }}/${{ env.PREVIEW_REPO }}/${{ env.PR_PATH}}/ ✨ 64 | 65 | Changes may take a few minutes to propagate. -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: Deploy to GitHub Pages 2 | 3 | on: 4 | # Runs on pushes targeting the default branch 5 | push: 6 | branches: ["main"] 7 | 8 | # Allows you to run this workflow manually from the Actions tab 9 | workflow_dispatch: 10 | 11 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 12 | permissions: 13 | contents: read 14 | pages: write 15 | id-token: write 16 | 17 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 18 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 19 | concurrency: 20 | group: "pages" 21 | cancel-in-progress: false 22 | 23 | jobs: 24 | # Build job 25 | build: 26 | runs-on: ubuntu-latest 27 | steps: 28 | - name: Checkout 29 | uses: actions/checkout@v4 30 | with: 31 | submodules: "true" 32 | 33 | - name: Setup Pages 34 | id: pages 35 | uses: actions/configure-pages@v5 36 | 37 | - name: Set up Python 38 | uses: actions/setup-python@v5 39 | with: 40 | python-version: "3.10" 41 | 42 | - name: Install dependencies 43 | run: pip install -r .devcontainer/requirements.txt 44 | 45 | - name: Build the docs site 46 | run: mkdocs build 47 | 48 | - name: Upload artifact 49 | uses: actions/upload-pages-artifact@v3 50 | with: 51 | name: github-pages 52 | path: "_site/" 53 | 54 | # Deployment job 55 | deploy: 56 | environment: 57 | name: github-pages 58 | url: ${{ steps.deployment.outputs.page_url }} 59 | runs-on: ubuntu-latest 60 | needs: build 61 | steps: 62 | - name: Deploy to GitHub Pages 63 | id: deployment 64 | uses: actions/deploy-pages@v4 65 | with: 66 | artifact_name: github-pages 67 | -------------------------------------------------------------------------------- /.github/workflows/preview-cleanup.yml: -------------------------------------------------------------------------------- 1 | name: Delete preview on PR close 2 | on: 3 | pull_request: 4 | types: [closed] 5 | 6 | jobs: 7 | delete_preview: 8 | runs-on: ubuntu-20.04 9 | env: 10 | PR_PATH: pull/${{github.event.number}} 11 | DOMAIN: gradle.github.io 12 | PREVIEW_REPO: community-site-preview 13 | 14 | permissions: 15 | pull-requests: write 16 | 17 | steps: 18 | - name: make empty dir 19 | run: mkdir public 20 | 21 | - name: delete folder 22 | uses: peaceiris/actions-gh-pages@v4 23 | with: 24 | deploy_key: ${{ secrets.PREVIEW_DEPLOYMENT_KEY }} 25 | external_repository: gradle/${{ env.PREVIEW_REPO }} 26 | publish_dir: ./public 27 | destination_dir: ${{ env.PR_PATH }} 28 | 29 | - name: Comment on PR 30 | uses: hasura/comment-progress@v2.3.0 31 | with: 32 | github-token: ${{ secrets.GITHUB_TOKEN }} 33 | repository: ${{ github.repository }} 34 | number: ${{ github.event.number }} 35 | id: deploy-preview 36 | message: > 37 | 🪓 PR closed, deleted preview at https://github.com/${{ env.PREVIEW_REPO }}/tree/gh-pages/${{ env.PR_PATH }}/ 38 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Publish the Release 2 | on: 3 | release: 4 | types: [published] 5 | 6 | permissions: 7 | contents: write 8 | 9 | jobs: 10 | cookbook-pdf: 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Checkout 14 | uses: actions/checkout@v4 15 | with: 16 | submodules: "true" 17 | 18 | - name: Set up Python 19 | uses: actions/setup-python@v5 20 | with: 21 | python-version: "3.10" 22 | 23 | - name: Install dependencies 24 | run: pip install -r .devcontainer/requirements.txt 25 | 26 | - name: Build the docs and the PDF 27 | run: BUILD_PDF=1 mkdocs build 28 | 29 | - name: Upload Release Asset 30 | id: upload-release-asset 31 | uses: actions/upload-release-asset@v1 32 | env: 33 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 34 | with: 35 | upload_url: ${{ github.event.release.upload_url }} 36 | asset_path: _site/pdf/cookbook.pdf 37 | asset_name: cookbook.pdf 38 | asset_content_type: application/pdf 39 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | 3 | _site 4 | .cache 5 | temp_dir 6 | /.idea/.gitignore 7 | /.idea/community.iml 8 | /.idea/misc.xml 9 | /.idea/modules.xml 10 | /.idea/vcs.xml 11 | 12 | .DS_Store 13 | 14 | pyvenv.cfg 15 | .venv/ 16 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "cSpell.words": [ 3 | "gradleup", 4 | "Gratatouille", 5 | "Multiplatform", 6 | "nmcp", 7 | "OSSRH", 8 | "Sonatype" 9 | ] 10 | } -------------------------------------------------------------------------------- /.vscode/tasks.json: -------------------------------------------------------------------------------- 1 | { 2 | // See https://go.microsoft.com/fwlink/?LinkId=733558 3 | // for the documentation about the tasks.json format 4 | "version": "2.0.0", 5 | "tasks": [ 6 | { 7 | "label": "mkdocs-serve", 8 | "type": "shell", 9 | "isBackground": true, 10 | "command": "mkdocs serve", 11 | "problemMatcher": { 12 | "owner": "custom", 13 | "pattern": { 14 | "regexp": "^.*(Error|Except).*$" 15 | }, 16 | "background": { 17 | "activeOnStart": true, 18 | "beginsPattern": ".*Building documentation.*", 19 | "endsPattern": ".*Serving on.*" 20 | } 21 | } 22 | }, 23 | { 24 | "label": "mkdocs-stop", 25 | "type": "shell", 26 | "command": "${command:workbench.action.terminal.kill}" 27 | } 28 | ] 29 | } 30 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Attribution-NonCommercial-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International 58 | Public License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-NonCommercial-ShareAlike 4.0 International Public License 63 | ("Public License"). To the extent this Public License may be 64 | interpreted as a contract, You are granted the Licensed Rights in 65 | consideration of Your acceptance of these terms and conditions, and the 66 | Licensor grants You such rights in consideration of benefits the 67 | Licensor receives from making the Licensed Material available under 68 | these terms and conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-NC-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution, NonCommercial, and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. NonCommercial means not primarily intended for or directed towards 126 | commercial advantage or monetary compensation. For purposes of 127 | this Public License, the exchange of the Licensed Material for 128 | other material subject to Copyright and Similar Rights by digital 129 | file-sharing or similar means is NonCommercial provided there is 130 | no payment of monetary compensation in connection with the 131 | exchange. 132 | 133 | l. Share means to provide material to the public by any means or 134 | process that requires permission under the Licensed Rights, such 135 | as reproduction, public display, public performance, distribution, 136 | dissemination, communication, or importation, and to make material 137 | available to the public including in ways that members of the 138 | public may access the material from a place and at a time 139 | individually chosen by them. 140 | 141 | m. Sui Generis Database Rights means rights other than copyright 142 | resulting from Directive 96/9/EC of the European Parliament and of 143 | the Council of 11 March 1996 on the legal protection of databases, 144 | as amended and/or succeeded, as well as other essentially 145 | equivalent rights anywhere in the world. 146 | 147 | n. You means the individual or entity exercising the Licensed Rights 148 | under this Public License. Your has a corresponding meaning. 149 | 150 | 151 | Section 2 -- Scope. 152 | 153 | a. License grant. 154 | 155 | 1. Subject to the terms and conditions of this Public License, 156 | the Licensor hereby grants You a worldwide, royalty-free, 157 | non-sublicensable, non-exclusive, irrevocable license to 158 | exercise the Licensed Rights in the Licensed Material to: 159 | 160 | a. reproduce and Share the Licensed Material, in whole or 161 | in part, for NonCommercial purposes only; and 162 | 163 | b. produce, reproduce, and Share Adapted Material for 164 | NonCommercial purposes only. 165 | 166 | 2. Exceptions and Limitations. For the avoidance of doubt, where 167 | Exceptions and Limitations apply to Your use, this Public 168 | License does not apply, and You do not need to comply with 169 | its terms and conditions. 170 | 171 | 3. Term. The term of this Public License is specified in Section 172 | 6(a). 173 | 174 | 4. Media and formats; technical modifications allowed. The 175 | Licensor authorizes You to exercise the Licensed Rights in 176 | all media and formats whether now known or hereafter created, 177 | and to make technical modifications necessary to do so. The 178 | Licensor waives and/or agrees not to assert any right or 179 | authority to forbid You from making technical modifications 180 | necessary to exercise the Licensed Rights, including 181 | technical modifications necessary to circumvent Effective 182 | Technological Measures. For purposes of this Public License, 183 | simply making modifications authorized by this Section 2(a) 184 | (4) never produces Adapted Material. 185 | 186 | 5. Downstream recipients. 187 | 188 | a. Offer from the Licensor -- Licensed Material. Every 189 | recipient of the Licensed Material automatically 190 | receives an offer from the Licensor to exercise the 191 | Licensed Rights under the terms and conditions of this 192 | Public License. 193 | 194 | b. Additional offer from the Licensor -- Adapted Material. 195 | Every recipient of Adapted Material from You 196 | automatically receives an offer from the Licensor to 197 | exercise the Licensed Rights in the Adapted Material 198 | under the conditions of the Adapter's License You apply. 199 | 200 | c. No downstream restrictions. You may not offer or impose 201 | any additional or different terms or conditions on, or 202 | apply any Effective Technological Measures to, the 203 | Licensed Material if doing so restricts exercise of the 204 | Licensed Rights by any recipient of the Licensed 205 | Material. 206 | 207 | 6. No endorsement. Nothing in this Public License constitutes or 208 | may be construed as permission to assert or imply that You 209 | are, or that Your use of the Licensed Material is, connected 210 | with, or sponsored, endorsed, or granted official status by, 211 | the Licensor or others designated to receive attribution as 212 | provided in Section 3(a)(1)(A)(i). 213 | 214 | b. Other rights. 215 | 216 | 1. Moral rights, such as the right of integrity, are not 217 | licensed under this Public License, nor are publicity, 218 | privacy, and/or other similar personality rights; however, to 219 | the extent possible, the Licensor waives and/or agrees not to 220 | assert any such rights held by the Licensor to the limited 221 | extent necessary to allow You to exercise the Licensed 222 | Rights, but not otherwise. 223 | 224 | 2. Patent and trademark rights are not licensed under this 225 | Public License. 226 | 227 | 3. To the extent possible, the Licensor waives any right to 228 | collect royalties from You for the exercise of the Licensed 229 | Rights, whether directly or through a collecting society 230 | under any voluntary or waivable statutory or compulsory 231 | licensing scheme. In all other cases the Licensor expressly 232 | reserves any right to collect such royalties, including when 233 | the Licensed Material is used other than for NonCommercial 234 | purposes. 235 | 236 | 237 | Section 3 -- License Conditions. 238 | 239 | Your exercise of the Licensed Rights is expressly made subject to the 240 | following conditions. 241 | 242 | a. Attribution. 243 | 244 | 1. If You Share the Licensed Material (including in modified 245 | form), You must: 246 | 247 | a. retain the following if it is supplied by the Licensor 248 | with the Licensed Material: 249 | 250 | i. identification of the creator(s) of the Licensed 251 | Material and any others designated to receive 252 | attribution, in any reasonable manner requested by 253 | the Licensor (including by pseudonym if 254 | designated); 255 | 256 | ii. a copyright notice; 257 | 258 | iii. a notice that refers to this Public License; 259 | 260 | iv. a notice that refers to the disclaimer of 261 | warranties; 262 | 263 | v. a URI or hyperlink to the Licensed Material to the 264 | extent reasonably practicable; 265 | 266 | b. indicate if You modified the Licensed Material and 267 | retain an indication of any previous modifications; and 268 | 269 | c. indicate the Licensed Material is licensed under this 270 | Public License, and include the text of, or the URI or 271 | hyperlink to, this Public License. 272 | 273 | 2. You may satisfy the conditions in Section 3(a)(1) in any 274 | reasonable manner based on the medium, means, and context in 275 | which You Share the Licensed Material. For example, it may be 276 | reasonable to satisfy the conditions by providing a URI or 277 | hyperlink to a resource that includes the required 278 | information. 279 | 3. If requested by the Licensor, You must remove any of the 280 | information required by Section 3(a)(1)(A) to the extent 281 | reasonably practicable. 282 | 283 | b. ShareAlike. 284 | 285 | In addition to the conditions in Section 3(a), if You Share 286 | Adapted Material You produce, the following conditions also apply. 287 | 288 | 1. The Adapter's License You apply must be a Creative Commons 289 | license with the same License Elements, this version or 290 | later, or a BY-NC-SA Compatible License. 291 | 292 | 2. You must include the text of, or the URI or hyperlink to, the 293 | Adapter's License You apply. You may satisfy this condition 294 | in any reasonable manner based on the medium, means, and 295 | context in which You Share Adapted Material. 296 | 297 | 3. You may not offer or impose any additional or different terms 298 | or conditions on, or apply any Effective Technological 299 | Measures to, Adapted Material that restrict exercise of the 300 | rights granted under the Adapter's License You apply. 301 | 302 | 303 | Section 4 -- Sui Generis Database Rights. 304 | 305 | Where the Licensed Rights include Sui Generis Database Rights that 306 | apply to Your use of the Licensed Material: 307 | 308 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 309 | to extract, reuse, reproduce, and Share all or a substantial 310 | portion of the contents of the database for NonCommercial purposes 311 | only; 312 | 313 | b. if You include all or a substantial portion of the database 314 | contents in a database in which You have Sui Generis Database 315 | Rights, then the database in which You have Sui Generis Database 316 | Rights (but not its individual contents) is Adapted Material, 317 | including for purposes of Section 3(b); and 318 | 319 | c. You must comply with the conditions in Section 3(a) if You Share 320 | all or a substantial portion of the contents of the database. 321 | 322 | For the avoidance of doubt, this Section 4 supplements and does not 323 | replace Your obligations under this Public License where the Licensed 324 | Rights include other Copyright and Similar Rights. 325 | 326 | 327 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 328 | 329 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 330 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 331 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 332 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 333 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 334 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 335 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 336 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 337 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 338 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 339 | 340 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 341 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 342 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 343 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 344 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 345 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 346 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 347 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 348 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 349 | 350 | c. The disclaimer of warranties and limitation of liability provided 351 | above shall be interpreted in a manner that, to the extent 352 | possible, most closely approximates an absolute disclaimer and 353 | waiver of all liability. 354 | 355 | 356 | Section 6 -- Term and Termination. 357 | 358 | a. This Public License applies for the term of the Copyright and 359 | Similar Rights licensed here. However, if You fail to comply with 360 | this Public License, then Your rights under this Public License 361 | terminate automatically. 362 | 363 | b. Where Your right to use the Licensed Material has terminated under 364 | Section 6(a), it reinstates: 365 | 366 | 1. automatically as of the date the violation is cured, provided 367 | it is cured within 30 days of Your discovery of the 368 | violation; or 369 | 370 | 2. upon express reinstatement by the Licensor. 371 | 372 | For the avoidance of doubt, this Section 6(b) does not affect any 373 | right the Licensor may have to seek remedies for Your violations 374 | of this Public License. 375 | 376 | c. For the avoidance of doubt, the Licensor may also offer the 377 | Licensed Material under separate terms or conditions or stop 378 | distributing the Licensed Material at any time; however, doing so 379 | will not terminate this Public License. 380 | 381 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 382 | License. 383 | 384 | 385 | Section 7 -- Other Terms and Conditions. 386 | 387 | a. The Licensor shall not be bound by any additional or different 388 | terms or conditions communicated by You unless expressly agreed. 389 | 390 | b. Any arrangements, understandings, or agreements regarding the 391 | Licensed Material not stated herein are separate from and 392 | independent of the terms and conditions of this Public License. 393 | 394 | 395 | Section 8 -- Interpretation. 396 | 397 | a. For the avoidance of doubt, this Public License does not, and 398 | shall not be interpreted to, reduce, limit, restrict, or impose 399 | conditions on any use of the Licensed Material that could lawfully 400 | be made without permission under this Public License. 401 | 402 | b. To the extent possible, if any provision of this Public License is 403 | deemed unenforceable, it shall be automatically reformed to the 404 | minimum extent necessary to make it enforceable. If the provision 405 | cannot be reformed, it shall be severed from this Public License 406 | without affecting the enforceability of the remaining terms and 407 | conditions. 408 | 409 | c. No term or condition of this Public License will be waived and no 410 | failure to comply consented to unless expressly agreed to by the 411 | Licensor. 412 | 413 | d. Nothing in this Public License constitutes or may be interpreted 414 | as a limitation upon, or waiver of, any privileges and immunities 415 | that apply to the Licensor or You, including from the legal 416 | processes of any jurisdiction or authority. 417 | 418 | ======================================================================= 419 | 420 | Creative Commons is not a party to its public 421 | licenses. Notwithstanding, Creative Commons may elect to apply one of 422 | its public licenses to material it publishes and in those instances 423 | will be considered the “Licensor.” The text of the Creative Commons 424 | public licenses is dedicated to the public domain under the CC0 Public 425 | Domain Dedication. Except for the limited purpose of indicating that 426 | material is shared under a Creative Commons public license or as 427 | otherwise permitted by the Creative Commons policies published at 428 | creativecommons.org/policies, Creative Commons does not authorize the 429 | use of the trademark "Creative Commons" or any other trademark or logo 430 | of Creative Commons without its prior written consent including, 431 | without limitation, in connection with any unauthorized modifications 432 | to any of its public licenses or any other arrangements, 433 | understandings, or agreements concerning use of licensed material. For 434 | the avoidance of doubt, this paragraph does not form part of the 435 | public licenses. 436 | 437 | Creative Commons may be contacted at creativecommons.org. 438 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Gradle Cookbook 2 | 3 | Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. 4 | This is a complementary resource to the official Gradle User Manual, which covers core capabilities maintained by the Gradle team. 5 | 6 | The goal of this portal is to offer solution-based documentation for end users about external integrations, 7 | including but not limited to CI/CD tools, IDEs, support for languages and frameworks, and various peripheral tools. 8 | 9 | ## Status 10 | 11 | > **WARNING:** Gradle Cookbook is an incubating project that is yet to reach the critical mass of content. 12 | > Any contributions will be appreciated! 13 | 14 | ## Contributing 15 | 16 | To contribute to this community repo, see [CONTRIBUTING.md](./docs/CONTRIBUTING.md). 17 | To contribute to the Gradle community as whole, we have the contributor guide [here](https://community.gradle.org/contributing/). 18 | All contributions are welcome! 19 | -------------------------------------------------------------------------------- /docs/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to the Gradle Cookbook 2 | 3 | [![a](https://img.shields.io/badge/slack-%23docs-brightgreen?style=flat&logo=slack)](https://gradle.org/slack-invite) 4 | 5 | 6 | The Gradle Cookbook is under active development. 7 | Any contributions are welcome! 8 | 9 | ## Discuss 10 | 11 | - `#docs` on the [Gradle Community Slack](https://gradle.org/slack-invite) 12 | - [GitHub Issues](https://github.com/gradle/community/issues) 13 | 14 | ## Development Environment 15 | 16 | Follow [this documentation](https://community.gradle.org/CONTRIBUTING/) for the community site. 17 | 18 | ## HOWTOs 19 | 20 | ### Editing and Adding Pages 21 | 22 | A few tips: 23 | 24 | - All the pages on this site are written in Markdown. 25 | - If needed, we have various tools available, such as code templates and macros, and we can add more MkDocs plugins if necessary. 26 | - The Table of Contents is currently located in [mkdocs.yml](https://github.com/gradle/cookbook/blob/main/mkdocs.yml). 27 | When adding new pages, please update the ToC to ensure they are discoverable. 28 | 29 | ### Adding New Categories 30 | 31 | At the moment, we add categories based on consensus. 32 | If you plan to add a new major category, it's better to discuss it in advance. 33 | 34 | ## Previews 35 | 36 | For any pull equest with the approved GitHub Actions run, 37 | a preview site will be deployed. 38 | The build both will share the link in the comments to the pull request. 39 | 40 | ## Building the Cookbook PDF 41 | 42 | Run `BUILD_PDF=1 mkdocs build` to generate the PDF file in [_site/pdf/cookbook.pdf](./../_site/pdf/cookbook.pdf). 43 | 44 | ## References 45 | 46 | - [Main Contributor Guide](https://community.gradle.org/contributing/) - describes how to contribute to Gradle 47 | -------------------------------------------------------------------------------- /docs/android/README.md: -------------------------------------------------------------------------------- 1 | 2 | # Gradle for Android 3 | 4 | Gradle is one of the most popular build tools in the Android ecosystem. It is used for [Kotlin and Kotlin Multiplatform](../kotlin/README.md), [Flutter](https://flutter.dev/), [React Native](https://reactnative.dev/), and other toolchains. 5 | 6 | ## Official Documentation 7 | 8 | The official documentation for Android development with Gradle is provided by Google and the community on the Android Developers site. You can find this documentation [here](https://developer.android.com/build). 9 | 10 | ## Featured Recipes 11 | 12 | - [Gradle build overview](https://developer.android.com/build/gradle-build-overview) - Understand how Gradle builds Android applications with Gradle using Android Gradle Plugin (AGP), key concepts, and the structure of a standard Android project. 13 | 14 | - [Android build management](https://developer.android.com/build) - Configure your Android builds for better packaging to test, build, sign, and distribute your app bundles and APKs. 15 | 16 | - [Managing dependencies](https://developer.android.com/build/dependencies) - Configure remote repositories to add external binaries or other library modules into your build as dependencies. 17 | 18 | - [Building project](https://developer.android.com/build/building-cmdline) - Execute tasks available for Android projects using the Gradle wrapper to build and deploy APKs and app bundles. 19 | 20 | - [Optimizing Builds](https://developer.android.com/build/optimize-your-build) - Configure your builds to decrease the build time, resulting in faster development of your Android projects. 21 | 22 | - [Extending AGP](https://developer.android.com/build/extend-agp) - AGP contains extension points for plugins to control build inputs and extend its functionality through new steps that can be integrated with standard build tasks. 23 | 24 | - [Migration Guide](https://developer.android.com/build/migrate-to-kotlin-dsl) - Guide for migrating from Groovy to Kotlin DSL, version catalogs, Kapt (Kotlin Annotation Processing Tool) to KSP (Kotlin Symbol Processing). 25 | 26 | - [Troubleshooting AGP](https://developer.android.com/build/troubleshoot) - Troubleshooting guide if you encounter issues with the Android Gradle Plugin (AGP). 27 | 28 | ## Expanded Sections 29 | 30 | ### **1. Gradle Build Overview** 31 | Gradle builds Android applications using the **Android Gradle Plugin (AGP)**, which provides the flexibility to define build types, product flavors, and dependencies. Understanding these key concepts is crucial for creating efficient and scalable Android projects. 32 | 33 | #### Key Concepts: 34 | - **Build Variants**: Manage multiple variants of your app such as `debug` and `release`. 35 | - **Build Types**: Use predefined types (e.g., `debug`, `release`) to control various build configurations. 36 | - **Kotlin DSL**: Gradle uses Kotlin DSL by default for better type safety and editor support in Android builds. 37 | 38 | #### Example in Kotlin DSL: 39 | ```kotlin 40 | android { 41 | buildTypes { 42 | release { 43 | minifyEnabled(true) 44 | proguardFiles( 45 | getDefaultProguardFile("proguard-android-optimize.txt"), 46 | "proguard-rules.pro" 47 | ) 48 | } 49 | } 50 | } 51 | ``` 52 | For more details, visit the [Gradle build overview](https://developer.android.com/build/gradle-build-overview). 53 | 54 | ### **2. Android Build Management** 55 | Android build management allows you to define various configurations for packaging, testing, signing, and distributing your app. The ability to manage product flavors, build types, and dynamic delivery modules ensures flexibility across different versions of your app. 56 | 57 | #### Example of Build Flavors: 58 | ```kotlin 59 | android { 60 | flavorDimensions("version") 61 | productFlavors { 62 | free { 63 | dimension = "version" 64 | } 65 | paid { 66 | dimension = "version" 67 | } 68 | } 69 | } 70 | ``` 71 | For more information, visit [Android build management](https://developer.android.com/build). 72 | 73 | ### **3. Managing Dependencies** 74 | Gradle enables the addition of external binaries or library modules as dependencies, which is essential for maintaining large Android projects. You can also use **version catalogs** to resolve dependency version conflicts and handle dependencies in **Kotlin Multiplatform** projects. 75 | 76 | #### Example of Dependencies in Kotlin DSL: 77 | ```kotlin 78 | dependencies { 79 | implementation("com.squareup.retrofit2:retrofit:2.9.0") 80 | implementation(platform("com.google.firebase:firebase-bom:26.7.0")) 81 | } 82 | ``` 83 | For more information, visit [Managing dependencies](https://developer.android.com/build/dependencies). 84 | 85 | ### **4. Building Projects** 86 | 87 | Gradle provides tasks for building your Android projects, including compiling code, packaging APKs, and generating app bundles. Using the **Gradle wrapper**, you can ensure build consistency across environments. 88 | 89 | #### Example of Building an APK with Kotlin DSL: 90 | 91 | ```kotlin 92 | tasks.register("customAssembleDebug") { 93 | doLast { 94 | println("Building APK in debug mode...") 95 | } 96 | } 97 | ``` 98 | This Kotlin example registers a task to build the APK in debug mode. For more detailed steps on building projects and packaging apps, visit the [Building Projects Guide](https://developer.android.com/build/building-cmdline). 99 | 100 | ### **5. Optimizing Builds** 101 | Gradle provides various options to improve build performance, including **build caching**, **parallel execution**, and **Gradle Daemon tuning**. These methods are especially beneficial for larger projects, helping to reduce build times and enhance productivity. 102 | 103 | #### Example of Enabling Parallel Execution: 104 | ```properties 105 | org.gradle.parallel=true 106 | ``` 107 | 108 | To explore more optimization techniques and configure your builds for better performance, check out our detailed guide: [Gradle Build Optimization](../../docs/android/optimization.md). 109 | 110 | For further information, visit the **official** [Optimizing Builds Guide](https://developer.android.com/build/optimize-your-build). 111 | 112 | ### **6. Extending AGP** 113 | You can extend the Android Gradle Plugin (AGP) by writing custom tasks and plugins to integrate new functionality into the existing build system. This allows for advanced customization and flexibility in your build processes. 114 | 115 | #### Example of a Custom Task: 116 | ```kotlin 117 | tasks.register("printHelloMessage") { 118 | doLast { 119 | println("Hello, Android Developers!") 120 | } 121 | } 122 | ``` 123 | For more information, visit [Extending AGP](https://developer.android.com/build/extend-agp). 124 | 125 | ### **7. Migration Guide** 126 | 127 | With the shift from **Groovy** to **Kotlin DSL** in the Android ecosystem, migrating your build scripts is essential. This guide helps you transition your build configurations and annotation processing from **Kapt** to **KSP**. 128 | 129 | For detailed steps and best practices, refer to the [official Migration Guide](https://developer.android.com/build/migrate-to-kotlin-dsl). 130 | 131 | ### **8. Troubleshooting AGP** 132 | 133 | Encountering issues with the Android Gradle Plugin (AGP) is common, and this section provides solutions to common problems such as dependency resolution failures, build script errors, and performance bottlenecks. 134 | 135 | #### Example of Dependency Conflict Resolution: 136 | ```kotlin 137 | configurations.all { 138 | resolutionStrategy { 139 | force("com.google.guava:guava:27.0.1-android") 140 | } 141 | } 142 | ``` 143 | For more troubleshooting tips, visit the **official** [Troubleshooting AGP](https://developer.android.com/build/troubleshoot) page. 144 | 145 | You can also check the [Gradle Troubleshooting](../../docs/android/troubleshooting.md) page for additional help with Gradle-specific issues. 146 | 147 | ## References 148 | 149 | - [Official Documentation](https://developer.android.com/build) 150 | - [AGP releases](https://developer.android.com/build/releases/gradle-plugin) 151 | - [Android Gradle Plugin API reference](https://developer.android.com/reference/tools/gradle-api) 152 | -------------------------------------------------------------------------------- /docs/android/optimization.md: -------------------------------------------------------------------------------- 1 | # Gradle Build Optimization 2 | 3 | This page references key external resources to help you optimize your Android Gradle builds. Below are some techniques and guides: 4 | 5 | - [Build Caching](https://developer.android.com/build/optimize-your-build#use-the-configuration-cache) – Reduce unnecessary tasks by reusing outputs from previous builds. 6 | - [Parallel Execution](https://docs.gradle.org/current/userguide/performance.html#parallel_execution) – Execute independent tasks in parallel to speed up the build. 7 | - [Gradle Daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html#enable_deamon) – Optimize build performance by using a persistent process for faster execution. 8 | 9 | More original content will be added soon to cover performance monitoring, advanced caching strategies, and Gradle tuning specific to large-scale projects. 10 | -------------------------------------------------------------------------------- /docs/android/troubleshooting.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting Android Gradle Plugin (AGP) 2 | 3 | This page serves as a resource for resolving common issues encountered while working with the Android Gradle Plugin (AGP). Below are some typical problems and solutions. 4 | 5 | ## Common Issues 6 | 7 | ### 1. Dependency Resolution Failures 8 | Dependency conflicts can arise when multiple libraries require different versions of the same dependency. Use the following example to enforce a specific version: 9 | 10 | ```kotlin 11 | configurations.all { 12 | resolutionStrategy { 13 | force("com.google.guava:guava:27.0.1-android") 14 | } 15 | } 16 | ``` 17 | 18 | ### 2. Build Script Errors 19 | Errors in the build script can prevent the project from compiling. Ensure that all plugins and dependencies are correctly defined. Review the logs for specific error messages that can guide you to the problem. 20 | 21 | ### 3. Performance Bottlenecks 22 | Build performance issues may occur due to improper configurations. To optimize your build time, consider using techniques like enabling build caching and parallel execution. 23 | 24 | ## Additional Resources 25 | - [Troubleshooting AGP](https://developer.android.com/build/troubleshoot) page. 26 | 27 | ## Contributing 28 | Feel free to add additional tips or common issues you encounter. Contributions are welcome to improve this troubleshooting guide. 29 | -------------------------------------------------------------------------------- /docs/assets/css/gradle.css: -------------------------------------------------------------------------------- 1 | 2 | /* TODO: proper styling */ 3 | :root { 4 | /* https://gradle.com/brand/ */ 5 | --gradle-bg-dark: #010002; 6 | --gradle-bg-gray: #F8F8F8; 7 | --gradle-bg-white: #FFFFFF; 8 | --gradle-blue: #209BC4; 9 | --gradle-blue-lite: #4DC9C0; 10 | 11 | 12 | --md-primary-fg-color: var(--gradle-bg-dark); 13 | --md-primary-fg-color--light: var(--gradle-bg-gray); 14 | --md-primary-fg-color--dark: var(--gradle-bg-dark); 15 | } 16 | 17 | .md-banner { 18 | div { 19 | text-align: center; 20 | a { 21 | color: var(--gradle-blue); 22 | font-weight: bold; 23 | } 24 | } 25 | } 26 | 27 | .md-content { 28 | --md-typeset-a-color: var(--gradle-blue); 29 | } 30 | 31 | /* 32 | .md-nav__item--section>.md-nav__link[for] { 33 | color: var(--gradle-blue-lite); 34 | }*/ 35 | 36 | .md-nav__link--active > span { 37 | color: var(--gradle-blue); 38 | font-weight: bold; 39 | } 40 | 41 | .md-typeset h1 { 42 | color: var(--gradle-dark); 43 | } 44 | 45 | h2 { 46 | color: var(--gradle-dark); 47 | } 48 | 49 | h3 { 50 | color: var(--gradle-dark); 51 | } 52 | 53 | h4 { 54 | color: var(--gradle-dark); 55 | } 56 | 57 | .youtube-video { 58 | overflow: hidden; 59 | position: relative; 60 | display: flex; 61 | justify-content: center; 62 | 63 | div { 64 | position: relative; 65 | height: 100%; 66 | width: 100%; 67 | aspect-ratio: 16/9; 68 | max-width: 900px; 69 | } 70 | 71 | iframe { 72 | position: absolute; 73 | top: 0; 74 | left: 0; 75 | width: 100%; 76 | height: 100%; 77 | } 78 | } 79 | 80 | .grid-container { 81 | display: flex; 82 | flex-wrap: wrap; 83 | margin-left: auto; 84 | margin-right: auto; 85 | gap: 1rem; 86 | vertical-align: middle; 87 | 88 | .card { 89 | display: block; 90 | border: .2rem solid; 91 | border-radius: 1rem; 92 | padding: 1rem; 93 | align-items: center; 94 | width: 48%; 95 | min-width: 320px; 96 | 97 | h3 { 98 | font-size: x-large; 99 | font-weight: bolder; 100 | span { 101 | margin-right: 0.5rem; 102 | .section-icon { 103 | width: 20px; 104 | height: 20px; 105 | } 106 | } 107 | } 108 | 109 | items { 110 | font-size: larger; 111 | font-weight: bold; 112 | } 113 | } 114 | } 115 | 116 | .button { 117 | display: inline-block; 118 | min-width: 180px; 119 | padding: 10px 20px; 120 | font-size: 17px; 121 | line-height: 1.4; 122 | text-align: center; 123 | font-size: large; 124 | font-weight: bold; 125 | white-space: nowrap; 126 | cursor: pointer; 127 | border-style: solid; 128 | border-width: 1px; 129 | border-radius: 8px; 130 | transition: background-color .3s ease, border .3s ease; 131 | } 132 | 133 | .icon { 134 | width: 20px; 135 | } 136 | 137 | .button--blue, 138 | .button--blue-lite { 139 | color: white; 140 | border-color: transparent; 141 | &:hover { 142 | color: white; 143 | } 144 | } 145 | 146 | 147 | .button--blue { 148 | border-color: var(--gradle-blue-lite); 149 | background: var(--gradle-blue); 150 | background: linear-gradient(var(--button-gradient-angle), var(--gradle-blue) 0%, var(--gradle-blue-lite) 100%); 151 | transition: none; 152 | &:hover { 153 | background-color: var(--gradle-blue-lite); 154 | color: white; 155 | } 156 | } 157 | 158 | 159 | .button--blue-lite { 160 | background-color: var(--gradle-bg-gray); 161 | &:hover { 162 | background-color: var(--gradle-blue-lite); 163 | color: white; 164 | } 165 | } 166 | -------------------------------------------------------------------------------- /docs/assets/images/logos/gradle-build-tool.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /docs/assets/images/logos/gradle.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 22 | 23 | 24 | -------------------------------------------------------------------------------- /docs/chapters.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Gradle Cookbook Chapters 3 | --- 4 | 5 | Below, you can see the list of the chapters 6 | that are currently available on the cookbook. 7 | More chapters will be added soon, contributions are [welcome](./CONTRIBUTING.md)!. 8 | 9 | ## Integrations 10 | 11 | - [Maven Central Publishing](./integrations/maven-central/publishing.md) 12 | - [Gradle on Continuous Integration](./ci/README.md) 13 | 14 | ## By Technology 15 | 16 | - [Gradle for Kotlin development](./kotlin/README.md) 17 | - [Gradle for Android development](./android/README.md) 18 | 19 | 20 | ## For Developers 21 | 22 | - [Troubleshooting Gradle issues and performance](./troubleshooting/README.md) 23 | - [Plugin Development](./plugin-development/README.md) 24 | -------------------------------------------------------------------------------- /docs/ci/README.md: -------------------------------------------------------------------------------- 1 | # Using Gradle with Continuous Integration Systems 2 | 3 | Gradle has many integrations with Continuous Integration (CI) 4 | and Continuous Delivery (CD) systems. 5 | Below you can find references to integrations and best practices. 6 | 7 | !!! warning 8 | This section is under active development. 9 | The pages might be outdated, contributions are welcome! 10 | 11 | ## Recipes 12 | 13 | - [GitHub Actions](./github-actions.md) 14 | - [GitLab CI](./gitlab-ci.md) 15 | - [Jenkins](jenkins.md) 16 | - [TeamCity](./teamcity.md) 17 | - [Travis CI](./travis-ci.md) 18 | 19 | ## External Pages 20 | 21 | - [Tekton task for Gradle](https://hub.tekton.dev/tekton/task/gradle) 22 | - [CircleCI orb for Gradle](https://circleci.com/developer/orbs/orb/circleci/gradle) 23 | 24 | -------------------------------------------------------------------------------- /docs/ci/github-actions.md: -------------------------------------------------------------------------------- 1 | # Executing Gradle builds on GitHub Actions 2 | 3 | !!! tip 4 | Top engineering teams using GitHub Actions have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. [Register here](https://dpeuniversity.gradle.com/app/courses/ec69d0b8-9171-4969-ac3e-82dea16f87b0) for our Build Cache training session to learn how your team can achieve similar results. 5 | 6 | Building Gradle projects doesn't stop with the developer's machine. [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) has been a long-established practice for running a build for every single change committed to version control to tighten the feedback loop. 7 | 8 | In this guide, we'll discuss how to configure [GitHub Actions](https://github.com/features/actions/) for a Gradle project hosted on GitHub. 9 | 10 | ## Introduction 11 | 12 | GitHub Actions is a cloud-based CI solution provider built directly into GitHub, making it an excellent choice for projects hosted on GitHub. Using the [setup-gradle](https://github.com/gradle/actions/tree/main/setup-gradle) GitHub Action makes it simple to integrate any Gradle project into a GitHub Actions workflow. 13 | 14 | ## What you'll need 15 | 16 | * A text editor 17 | * A command prompt 18 | * The Java Development Kit (JDK), version 1.8 or higher 19 | * A local Gradle installation, to initialize a new Gradle project 20 | * A GitHub account 21 | 22 | ## Setup a Gradle project on GitHub 23 | 24 | If you have an existing Gradle project hosted on GitHub, then you can skip this step and move directly to [Configure GitHub Actions](#configure-github-actions). 25 | 26 | If not, follow these steps to initialize a new Gradle project on GitHub. 27 | 28 | ### Create a new GitHub repository for your project 29 | 30 | Via the GitHub user interface, create a new repository named `github-actions-gradle-sample`. 31 | 32 | ![Create new GitHub repository](images/github-actions-create-repository.png) 33 | 34 | ### Clone the repository locally 35 | 36 | ```shell 37 | $ git clone git@github.com:/github-actions-gradle-sample.git 38 | Cloning into 'github-actions-gradle-sample'... 39 | $ cd github-actions-gradle-sample 40 | ``` 41 | 42 | ### Initialize the Gradle project and commit to the repository 43 | 44 | Use `gradle init` to create a fresh Gradle project. You can choose any of the available options during `init`, but we recommend choosing "library" as the project type. 45 | 46 | Once the project is generated, commit the changes and push to the repository. 47 | 48 | ```shell 49 | $ gradle init 50 | $ git add . 51 | $ git commit -m "Initial commit" 52 | $ git push 53 | ``` 54 | 55 | ### Test building the project 56 | 57 | The project uses the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) for building the project. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. 58 | 59 | Before asking GitHub Actions to build your project, it's useful to ensure that it builds locally. Adding the "CI" environment variable will emulate running the build on GitHub Actions. 60 | 61 | The following command achieves that: 62 | 63 | ```shell 64 | $ CI=true ./gradlew build 65 | 66 | BUILD SUCCESSFUL 67 | ``` 68 | 69 | If the build works as expected, we are ready to build it with GitHub Actions. 70 | 71 | ## Configure GitHub Actions 72 | 73 | You can create a GitHub Actions workflow by adding a `.github/workflows/.yml` file to your repository. This workflow definition file contains all relevant instructions for building the project on GitHub Actions. 74 | 75 | The following workflow file instructs GitHub Actions to build your Gradle project using the Gradle Wrapper, executed by the default Java distribution for GitHub Actions. Create a new file named `.github/workflows/build-gradle-project.yml` with the following content, and push it to the GitHub repository. 76 | 77 | ```yaml 78 | name: Build Gradle project 79 | 80 | on: 81 | push: 82 | 83 | jobs: 84 | build-gradle-project: 85 | runs-on: ubuntu-latest 86 | steps: 87 | - name: Checkout project sources 88 | uses: actions/checkout@v4 89 | 90 | - name: Setup Gradle 91 | uses: gradle/actions/setup-gradle@v3 92 | with: 93 | build-scan-publish: true 94 | build-scan-terms-of-use-url: "https://gradle.com/terms-of-service" 95 | build-scan-terms-of-use-agree: "yes" 96 | 97 | - name: Run build 98 | run: ./gradlew build 99 | ``` 100 | 101 | [Gradle Build Scans®](https://scans.gradle.com) are a great way to view your build results and provide valuable insights into your build. The workflow is configured to automatically publish a Build Scan for each build, accepting the legal terms of use. If you don't wish to publish Build Scans, you can remove this configuration from the workflow. 102 | 103 | Commit the changes and push to the repository: 104 | 105 | ```shell 106 | $ git add . 107 | $ git commit -m "Add GitHub Actions workflow" 108 | $ git push 109 | ``` 110 | 111 | ## View the GitHub Actions results 112 | 113 | Once this workflow file is pushed, you should immediately see the workflow execution in the GitHub Actions page for your repository (e.g., https://github.com/gradle/gradle/actions). Any subsequent push to the repository will trigger the workflow to run. 114 | 115 | ### List all runs of the GitHub Actions workflow 116 | 117 | The main actions page can be used to list all runs for a GitHub Actions workflow. 118 | 119 | ![View workflow executions](images/github-actions-workflows.png) 120 | 121 | ### See the results for GitHub Actions workflow run 122 | 123 | Clicking on the link for a workflow run will show the details of the workflow run, including a summary of all Gradle builds with links to any Build Scan published. 124 | 125 | **TIP:** Configuring [build scans](https://scans.gradle.com) is especially helpful on cloud CI systems like GitHub Actions because it has additional environment and test results information that are difficult to obtain otherwise. 126 | 127 | ![View workflow execution details](images/github-actions-workflow.png) 128 | 129 | ### View the details for Jobs and Steps in the workflow 130 | 131 | Finally, you can view the logs for the individual workflow Jobs and each Step defined for a Job: 132 | 133 | ![View workflow job details](images/github-actions-job-details.png) 134 | 135 | ## Enable caching of downloaded artifacts 136 | 137 | The [setup-gradle](https://github.com/gradle/actions/tree/main/setup-gradle) action used by this workflow will enable saving and restoring of the Gradle User Home directory in the built-in GitHub Actions cache. This will speed up your GitHub Actions build by avoiding the need to re-download Gradle versions and project dependencies, as well as re-using state from the previous workflow execution. 138 | 139 | Details about what entries are saved/restored from the cache can be viewed in the generated Job Summary: 140 | 141 | ![View cache entry details](images/github-actions-cache-details.png) 142 | 143 | ## Detect vulnerable dependencies with a dependency-submission workflow 144 | 145 | [GitHub supply chain security](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security) features will detect and alert about any dependencies that have known vulnerabilities. In order to do this, GitHub requires a complete dependency graph for your project. 146 | 147 | **NOTE:** Ensure that you have both [Dependency graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph) and [Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#managing-dependabot-alerts-for-your-repository) enabled for your repository. 148 | 149 | The [dependency-submission](https://github.com/gradle/actions/tree/main/dependency-submission) action for Gradle provides the simplest way to generate a dependency graph for your project. This action will attempt to detect and upload a list of all dependencies used by your build. 150 | 151 | We recommend a separate GitHub Actions workflow for dependency submission. Create a GitHub Actions workflow by adding a `.github/workflows/.yml` file to your repository. Create a new file named `.github/workflows/gradle-dependency-submission.yml` with the following content, and push it to the GitHub repository. 152 | 153 | ```yaml 154 | name: Gradle Dependency Submission 155 | 156 | on: 157 | push: 158 | branches: 159 | - main 160 | 161 | jobs: 162 | dependency-submission: 163 | runs-on: ubuntu-latest 164 | steps: 165 | - name: Checkout project sources 166 | uses: actions/checkout@v4 167 | 168 | - name: Generate and submit dependency graph 169 | uses: gradle/actions/dependency-submission@v3 170 | with: 171 | build-scan-publish: true 172 | build-scan-terms-of-use-url: "https://gradle.com/terms-of-service" 173 | build-scan-terms-of-use-agree: "yes" 174 | ``` 175 | 176 | [Gradle Build Scans®](https://scans.gradle.com) are a great way to view your build results and provide valuable insights into your build. The workflow is configured to automatically publish a Build Scan for each build, accepting the legal terms of use. If you don't wish to publish Build Scans, you can remove this configuration from the workflow. 177 | 178 | Commit the changes and push to the repository: 179 | 180 | ```shell 181 | $ git add . 182 | $ git commit -m "Add Dependency submission workflow" 183 | $ git push 184 | ``` 185 | 186 | ### Viewing the dependency graph 187 | 188 | Once the dependency-submission workflow has completed, you can view all reported dependencies by navigating to `Insights -> Dependency graph`. 189 | 190 | This image reveals that the repository contains a version of `com.google.guava:guava` with a moderate vulnerability. 191 | 192 | ![View dependency graph](images/github-actions-dependency-graph.png) 193 | 194 | ### Viewing all dependency alerts 195 | 196 | You can view a list of all vulnerabilities by navigating to `Security -> Dependabot`. 197 | 198 | ![View dependency alerts](images/github-actions-dependency-alerts.png) 199 | -------------------------------------------------------------------------------- /docs/ci/gitlab-ci.md: -------------------------------------------------------------------------------- 1 | # Executing Gradle builds on GitLab CI 2 | 3 | !!! tip 4 | Top engineering teams using GitLab CI have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. https://gradle.org/training/#build-cache-deep-dive[Register here] for our Build Cache training session to learn how your team can achieve similar results. 5 | 6 | Building Gradle projects doesn't stop with the developer's machine. 7 | https://en.wikipedia.org/wiki/Continuous_integration[Continuous Integration] (CI) has been a long-established practice for running a build for every single change committed to version control to tighten the feedback loop. 8 | 9 | In this guide, we'll discuss how to configure link:https://docs.gitlab.com/ee/ci/[GitLab CI] for a Gradle project hosted on GitLab (GitLab.com, self-managed or dedicated). 10 | 11 | ## Introduction 12 | 13 | GitLab CI is a cloud-based CI solution provider built directly into GitLab, making it an excellent choice for projects hosted on GitLab. 14 | 15 | ## What you'll need 16 | 17 | * A text editor 18 | * A command prompt 19 | * The Java Development Kit (JDK), version 1.8 or higher 20 | * A local Gradle installation to initialize a new Gradle project 21 | * A GitLab instance (any tier, any deployment type) 22 | * A GitLab account on the instance you want to use 23 | 24 | ## Setup a Gradle project on GitLab 25 | 26 | If you have a Gradle project hosted on GitLab, you can skip this step and move directly to [Configure GitLab CI](.#configure-gitlab-ci) 27 | 28 | If not, follow these steps to initialize a new Gradle project on GitLab. 29 | 30 | ### Create a new GitLab repository for your project 31 | 32 | Create a new repository named `gitlab-ci-gradle-sample` via the GitLab user interface. 33 | 34 | ![Create new GitHub repository](images/gitlab-ci-create-repository.png) 35 | 36 | ### Clone the repository locally 37 | 38 | ```shell 39 | $ git clone git@example.gitlab.com:/gitlab-ci-gradle-sample.git 40 | Cloning into 'gitlab-ci-gradle-sample'... 41 | $ cd gitlab-ci-gradle-sample 42 | ``` 43 | 44 | ### Initialize the Gradle project and commit to the repository 45 | 46 | Use `gradle init` to create a fresh Gradle project. You can choose any available options during `init`, but we recommend choosing "library" as the project type. 47 | 48 | Once the project is generated, commit the changes and push to the repository. 49 | 50 | ```shell 51 | $ gradle init 52 | $ git add . 53 | $ git commit -m "Initial commit" 54 | $ git push 55 | ``` 56 | 57 | ### Enable Build Scan™ publishing 58 | 59 | [Gradle Build Scans](https://scans.gradle.com) are a great way to view your build results and provide valuable insights into your build. 60 | To publish Build Scans from GitLab CI, you'll need to pre-approve the Terms & Conditions. 61 | 62 | To do so, add the following content to the top of your `settings.gradle[.kts]` file. GitLab CI sets the "CI" environment variable: 63 | 64 | ```groovy 65 | plugins { 66 | id("com.gradle.enterprise") version("3.16.2") 67 | } 68 | 69 | gradleEnterprise { 70 | if (System.getenv("CI") != null) { 71 | buildScan { 72 | publishAlways() 73 | termsOfServiceUrl = "https://gradle.com/terms-of-service" 74 | termsOfServiceAgree = "yes" 75 | } 76 | } 77 | } 78 | ``` 79 | 80 | ### Test building the project 81 | 82 | The project uses the Gradle Wrapper for building the project. 83 | It is a recommended practice for any Gradle project as it enables your project to build on CI without installing the Gradle runtime. 84 | 85 | Before asking GitLab CI to build your project, it's useful to ensure that it builds locally. 86 | Adding the "CI" environment variable will emulate running the build on GitLab CI. 87 | 88 | The following command achieves that: 89 | 90 | ```shell 91 | $ CI=true ./gradlew build 92 | 93 | BUILD SUCCESSFUL 94 | 95 | Publishing build scan... 96 | https://gradle.com/s/7mtynxxmesdio 97 | ``` 98 | 99 | If the build works as expected, commit the changes and push to the repository. 100 | 101 | 102 | ```shell 103 | $ git commit -a -m "Publish Build Scans from GitLab CI" 104 | $ git push 105 | ``` 106 | 107 | ## Configure GitLab CI 108 | 109 | You can create a GitLab CI pipeline by adding a `.gitlab-ci.yml` file to your repository. 110 | This pipeline definition file contains all relevant instructions for building the project on Gitlab CI. 111 | 112 | The following workflow file instructs GitLab CI to build your Gradle project using the Gradle Wrapper, executed by the Eclipse Temurin JDK. 113 | Create a new file named `.gitlab-ci.yml` with the following content, and push it to the GitLab repository. 114 | 115 | ```yaml 116 | build-gradle-project: 117 | image: eclipse-temurin:latest 118 | 119 | script: 120 | - ./gradlew build 121 | 122 | artifacts: 123 | reports: 124 | junit: '**/build/test-results/**/TEST-*.xml' 125 | ``` 126 | 127 | This file defines a single job that executes the `./gradlew build` command. 128 | 129 | * The `image` field defines which Docker image the job will run in. Thanks to the Gradle Wrapper, only a JDK is necessary. 130 | * The `artifacts` field defines files generated by the job that GitLab CI should save. In particular, saving the JUnit report generated by the Gradle test tasks allows test results to be displayed directly in the Merge Request or Pipeline pages. 131 | 132 | Commit the changes and push them to the repository: 133 | 134 | ```shell 135 | $ git add . 136 | $ git commit -m "Add GitLab CI pipeline" 137 | $ git push 138 | ``` 139 | 140 | ## View the GitLab CI results 141 | 142 | Once this pipeline file is pushed, you should immediately see the pipeline execution in the GitLab CI page for your repository (e.g., `https://gitlab.com/username/repository/-/pipelines`). 143 | Any subsequent push to the repository will trigger the pipeline to run. 144 | 145 | ## Enable caching 146 | 147 | By default, no files are persisted between CI runs, so each job must download all dependencies again. We can configure GitLab to cache some files between jobs. This is especially efficient when running your own GitLab CI runner, as the cache is stored locally on the runner. 148 | 149 | CAUTION: The publicly available shared runners store their cache in a remote location. As the cache grows, downloading the cache archive, extracting it, and uploading it again at the end of the job may take more time than not using any cache. For this reason, we recommend only caching the Gradle Wrapper. For caching of intermediate build results, see configuring a [Gradle Remote Build Cache](https://docs.gradle.org/current/userguide/build_cache.html). To cache external dependencies used in builds, it is best to set up a dedicated repository manager in your infrastructure and configure it as a proxy for those dependencies. Solutions like [Sonatype Nexus](https://hub.docker.com/r/sonatype/nexus3/) or [JFrog Artifactory](https://jfrog.com/) can be used to act as a repository manager. 150 | 151 | To reuse some files between jobs, add the following configuration to your existing jobs: 152 | 153 | ```yaml 154 | build-gradle-project: 155 | # …existing configuration… 156 | 157 | variables: 158 | GRADLE_USER_HOME: $CI_PROJECT_DIR/.gradle 159 | 160 | cache: 161 | paths: 162 | - .gradle/wrapper 163 | key: 164 | files: 165 | - gradle/wrapper/gradle-wrapper.properties 166 | ``` 167 | 168 | Commit the changes and push to the repository: 169 | 170 | ```shell 171 | $ git add . 172 | $ git commit -m "Cache the Gradle Wrapper between CI jobs" 173 | $ git push 174 | ``` 175 | 176 | ## Further reading 177 | 178 | Learn more about building Gradle projects with GitLab CI: 179 | 180 | * [GitLab CI documentation](https://docs.gitlab.com/ee/ci/) 181 | * [.gitlab-ci.yml syntax reference](https://docs.gitlab.com/ee/ci/yaml/) 182 | * [Predefined variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) 183 | * [Avoiding duplication between multiple jobs](https://docs.gitlab.com/ee/ci/yaml/yaml_optimization.html) 184 | 185 | ## Summary 186 | 187 | Setting up and configuring Gradle builds on CI is straightforward, requiring just a few steps. 188 | The benefit of receiving fast feedback clearly speaks for itself. 189 | GitLab CI offers a simple and convenient mechanism to set up CI for any Gradle project hosted on GitLab. 190 | -------------------------------------------------------------------------------- /docs/ci/images/github-actions-cache-details.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/github-actions-cache-details.png -------------------------------------------------------------------------------- /docs/ci/images/github-actions-create-repository.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/github-actions-create-repository.png -------------------------------------------------------------------------------- /docs/ci/images/github-actions-dependency-alerts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/github-actions-dependency-alerts.png -------------------------------------------------------------------------------- /docs/ci/images/github-actions-dependency-graph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/github-actions-dependency-graph.png -------------------------------------------------------------------------------- /docs/ci/images/github-actions-job-details.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/github-actions-job-details.png -------------------------------------------------------------------------------- /docs/ci/images/github-actions-workflow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/github-actions-workflow.png -------------------------------------------------------------------------------- /docs/ci/images/github-actions-workflows.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/github-actions-workflows.png -------------------------------------------------------------------------------- /docs/ci/images/gitlab-ci-create-repository.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/gitlab-ci-create-repository.png -------------------------------------------------------------------------------- /docs/ci/images/jenkins-build-scan.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/jenkins-build-scan.png -------------------------------------------------------------------------------- /docs/ci/images/jenkins-build-step.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/jenkins-build-step.png -------------------------------------------------------------------------------- /docs/ci/images/jenkins-scm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/jenkins-scm.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-build-scan-plugin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-build-scan-plugin.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-build-step.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-build-step.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-create-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-create-project.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-log-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-log-link.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-results.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-results.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-scan.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-scan.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-step-added.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-step-added.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-step-upd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-step-upd.png -------------------------------------------------------------------------------- /docs/ci/images/teamcity-tests.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/teamcity-tests.png -------------------------------------------------------------------------------- /docs/ci/images/travis-enable-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gradle/cookbook/802779a189da0f003bb05436cda3855431d656a8/docs/ci/images/travis-enable-project.png -------------------------------------------------------------------------------- /docs/ci/jenkins.md: -------------------------------------------------------------------------------- 1 | # Executing Gradle builds on Jenkins 2 | 3 | !!! tip 4 | Top engineering teams using Jenkins have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. [Register here](https://dpeuniversity.gradle.com/app/courses/ec69d0b8-9171-4969-ac3e-82dea16f87b0) for our Build Cache training session to learn how your team can achieve similar results. 5 | 6 | Building Gradle projects doesn't stop with the developer's machine. [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) has been a long-established practice for running a build for every single change committed to version control to tighten the feedback loop. 7 | 8 | In this guide, we'll discuss how to configure [Jenkins](https://jenkins.io/) for a typical Gradle project. 9 | 10 | ## What you'll need 11 | 12 | - A text editor 13 | - A command prompt 14 | - The Java Development Kit (JDK), version 1.7 or higher 15 | - A Jenkins installation (setup steps explained in this post) 16 | 17 | ## Setup a typical project 18 | 19 | As an example, this guide is going to focus on a Java-based project. More specifically, a Gradle plugin written in Java and tested with [Spek](https://www.spekframework.org/). First, we'll get the project set up on your local machine before covering the same steps on CI. 20 | 21 | Just follow these steps: 22 | 23 | ### Clone the [Gradle Site Plugin](https://github.com/gradle/gradle-site-plugin) repository 24 | 25 | ```bash 26 | $ git clone https://github.com/gradle/gradle-site-plugin.git 27 | Cloning into 'gradle-site-plugin'... 28 | $ cd gradle-site-plugin 29 | ``` 30 | 31 | ### Build the project 32 | 33 | As a developer of a Java project, you'll typically want to compile the source code, run the tests, and assemble the JAR artifact. That's no different for Gradle plugins. The following command achieves exactly that: 34 | 35 | ```bash 36 | $ ./gradlew build 37 | 38 | BUILD SUCCESSFUL 39 | 14 actionable tasks: 14 executed 40 | ``` 41 | 42 | The project provides the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) as part of the repository. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. 43 | 44 | ### Build scan integration 45 | 46 | The sample project is equipped with support for generating [build scans](https://scans.gradle.com/). Running the build with the command line option `--scan` renders a link in the console. 47 | 48 | ```bash 49 | $ ./gradlew build --scan 50 | 51 | Publishing build scan... 52 | https://gradle.com/s/7mtynxxmesdio 53 | ``` 54 | 55 | The following section will describe how to build the project with the help of Jenkins. 56 | 57 | ## Setup Jenkins 58 | 59 | Jenkins is one of the most prominent players in the field. In the course of this section, you'll learn how to set up Jenkins, configure a job to pull the source code from GitHub, and run the Gradle build. 60 | 61 | ### Install and start Jenkins 62 | 63 | On the [Jenkins website](https://jenkins.io/download/), you can pick from a variety of distributions. This post uses the runnable WAR file. A simple Java command brings up the Jenkins server. 64 | 65 | ```bash 66 | $ wget https://mirrors.jenkins.io/war-stable/latest/jenkins.war 67 | $ java -jar jenkins.war 68 | ``` 69 | 70 | In the browser, navigate to `localhost` with port `8080` to render the Jenkins dashboard. You will be asked to set up a new administration user and which plugins to install. 71 | 72 | ### Installation of plugins 73 | 74 | Confirm to install the recommended plugins when starting Jenkins for the first time. Under "Manage Jenkins > Manage Plugins," ensure that you have the following two plugins installed: 75 | 76 | - [Git plugin](https://plugins.jenkins.io/git) 77 | - [Gradle plugin](https://plugins.jenkins.io/gradle) 78 | 79 | Next, we can set up the job for building the project. 80 | 81 | ## Create a Jenkins job 82 | 83 | Setting up a new Gradle job can be achieved with just a couple of clicks. From the left navigation bar, select "New Item > Freestyle project". Enter a new name for the project. We'll pick "gradle-site-plugin" for the project. 84 | 85 | Select the radio button "Git" in the section "Source Code Management". Enter the URL of the GitHub repository: `https://github.com/gradle/gradle-site-plugin.git`. 86 | 87 | ![Source Code Management](images/jenkins-scm.png) 88 | 89 | Furthermore, create a "Build step" in the section "Build" by selecting "Invoke Gradle script". As mentioned before, we'll want to use the Wrapper to execute the build. In the "Tasks" input box, enter `build` and use the "Switches" `--scan -s` to generate a build scan and render a stack trace in case of a build failure. 90 | 91 | ![Build Step](images/jenkins-build-step.png) 92 | 93 | ### Execute the job 94 | 95 | Save the configuration of the job and execute an initial build by triggering the "Build Now" button. The build should finish successfully and render a "Gradle Build Scan" icon that brings you directly to the [build scan](https://scans.gradle.com) for the given build. 96 | 97 | ![Build Scan](images/jenkins-build-scan.png) 98 | 99 | There are various options to trigger Jenkins builds continuously: from polling the repository periodically, to building on a set schedule, or via callback URL. 100 | 101 | ## Further reading 102 | 103 | You can learn more about advanced Jenkins usage through these resources: 104 | 105 | - [Using credentials with Jenkins](https://jenkins.io/doc/book/using/using-credentials/) 106 | - [Pipeline as code with Jenkins](https://jenkins.io/solutions/pipeline/) 107 | - [Modeling a Continuous Deployment pipeline for a Spring Boot application](https://bmuschko.com/blog/jenkins-build-pipeline/) 108 | 109 | ## Summary 110 | 111 | Executing Gradle builds on CI can be set up and configured with just a handful of steps. The benefit of receiving fast feedback clearly speaks for itself. If you are not using Jenkins, no problem, many CI products tightly integrate with Gradle as a first-class citizen. -------------------------------------------------------------------------------- /docs/ci/teamcity.md: -------------------------------------------------------------------------------- 1 | # Executing Gradle builds on TeamCity 2 | 3 | !!! tip 4 | Top engineering teams using TeamCity have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. [Register here](https://dpeuniversity.gradle.com/app/courses/ec69d0b8-9171-4969-ac3e-82dea16f87b0) for our Build Cache training session to learn how your team can achieve similar results. 5 | 6 | Building Gradle projects doesn't stop with the developer's machine. [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) has been a long-established practice for running a build for every single change committed to version control to tighten the feedback loop. 7 | 8 | In this guide, we'll discuss how to configure [TeamCity](https://www.jetbrains.com/teamcity/) for a typical Gradle project. 9 | 10 | ## What you'll need 11 | 12 | - A command prompt 13 | - The Java Development Kit (JDK), version 1.8 or higher 14 | - A TeamCity installation (setup steps explained in this guide) 15 | 16 | ## Setup a typical project 17 | 18 | For demonstration purposes, this guide is going to focus on building a Java-based project; however, this setup will work with any Gradle-compatible project. More specifically, a Gradle plugin written in Java and tested with [Spek](https://www.spekframework.org/). First, we'll get the project set up on your local machine before covering the same steps on CI. 19 | 20 | Just follow these steps: 21 | 22 | ### Clone the [Gradle Site Plugin](https://github.com/gradle/gradle-site-plugin) repository 23 | 24 | ```bash 25 | $ git clone https://github.com/gradle/gradle-site-plugin.git 26 | Cloning into 'gradle-site-plugin'... 27 | $ cd gradle-site-plugin 28 | ``` 29 | 30 | ### Build the project 31 | 32 | As a developer of a Java project, you'll typically want to compile the source code, run the tests, and assemble the JAR artifact. That's no different for Gradle plugins. The following command achieves exactly that: 33 | 34 | ```bash 35 | $ ./gradlew build 36 | 37 | BUILD SUCCESSFUL 38 | 14 actionable tasks: 14 executed 39 | ``` 40 | 41 | The project provides the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) as part of the repository. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. 42 | 43 | ### Build scan integration 44 | 45 | The sample project is equipped with support for generating [build scans](https://scans.gradle.com/). Running the build with the command line option `--scan` renders a link in the console. 46 | 47 | ```bash 48 | $ ./gradlew build --scan 49 | Publishing build scan... 50 | https://gradle.com/s/7mtynxxmesdio 51 | ``` 52 | 53 | ## Setup TeamCity 54 | 55 | JetBrains TeamCity is a powerful and user-friendly Continuous Integration and Deployment server that works out of the box. JetBrains offers several licensing options that allow you to scale TeamCity to your needs. In this setup, we'll use TeamCity Professional, a free fully functional edition suitable for average projects. In the course of this section, you'll learn how to set up TeamCity, create a build configuration to pull the source code from GitHub, and run the Gradle build. 56 | 57 | ### Install and start TeamCity 58 | 59 | On the [TeamCity website](https://www.jetbrains.com/teamcity/download/), you can pick from a variety of distributions. This post uses TeamCity bundled with Tomcat servlet container and covers the evaluation setup of a TeamCity server and a default build agent running on the same machine. 60 | 61 | 1. Make sure you have JRE or JDK installed and the JAVA_HOME environment variable is pointing to the Java installation directory. Oracle Java 1.8 JDK is required. 62 | 2. Download TeamCity .tar.gz distribution. Unpack the `TeamCity.tar.gz` archive, for example, using the WinZip, WinRar or a similar utility under Windows, or the following command under Linux or macOS: 63 | 64 | ```bash 65 | tar xfz TeamCity.tar.gz 66 | ``` 67 | 68 | 3. Start the TeamCity server and one default agent at the same time, using the runAll script provided in the `/bin` directory, e.g. 69 | 70 | ```bash 71 | runAll.sh start 72 | ``` 73 | 74 | 4. To access the TeamCity Web UI, navigate to `http://localhost:8111/`. Follow the defaults of the TeamCity setup. You will be asked to set up a new administration user. 75 | 76 | Next, we can set up the project and run a build in TeamCity. 77 | 78 | ## Create a TeamCity build 79 | 80 | Setting up a new Gradle build in TeamCity requires just a few clicks: TeamCity comes bundled with a Gradle plugin, so you do not need to install plugins additionally. However, it is recommended that you install the [TeamCity Build Scan plugin](https://plugins.jetbrains.com/plugin/9326-gradle-build-scan-integration). 81 | 82 | On the **Administration | Projects** page click _Create project_, use the option _From the repository URL_ and enter the URL of the GitHub repository: `https://github.com/gradle/gradle-site-plugin.git`. 83 | 84 | ![Source Code Management](images/teamcity-create-project.png) 85 | 86 | Follow the _Create Project_ wizard, it will prompt for the project and build configuration name and automatically detect build steps. Select the automatically Gradle build step and click _Use selected_: 87 | 88 | ![Build Step](images/teamcity-build-step.png) 89 | 90 | The build step is added to the build configuration: 91 | 92 | ![Step Added](images/teamcity-step-added.png) 93 | 94 | Click _Edit_, on the page that opens click _Advanced options_. Using the Wrapper to execute the build is considered good practice with Gradle, and on automatic detection, this option is selected by default. We’ll want to generate a build scan, so we’ll enter the `--scan` option in _Additional Gradle command line parameters_ field. 95 | 96 | ![Scan Option](images/teamcity-scan.png) 97 | 98 | Save the settings and we’re ready to run the build. 99 | 100 | ### Run the build in TeamCity 101 | 102 | Click the _Run_ button in the top right corner: 103 | 104 | ![Run Build](images/teamcity-step-upd.png) 105 | 106 | TeamCity will start the build and you’ll be able to view the build progress by clicking _Build Configuration Home_. When the build is finished, you can review the build results by clicking the build number link: 107 | 108 | ![Build Results](images/teamcity-results.png) 109 | 110 | You can view the tests right here in TeamCity: 111 | 112 | ![Tests](images/teamcity-tests.png) 113 | 114 | The information on parameters and environment of the build is available on the _Parameters_ tab of the build results. 115 | 116 | If you installed the [TeamCity Build Scan plugin](https://plugins.jetbrains.com/plugin/9326-gradle-build-scan-integration), you will see a link to the build scan in the Build Results view: 117 | 118 | ![Build Scan Plugin](images/teamcity-build-scan-plugin.png) 119 | 120 | Otherwise, the link to the [build scan](https://scans.gradle.com) for the given build is available in the build log: 121 | 122 | ![Build Log Link](images/teamcity-log-link.png) 123 | 124 | There are various options to trigger TeamCity builds continuously: from [polling the repository](https://www.jetbrains.com/help/teamcity/configuring-build-triggers.html) periodically, to [building on a set schedule](https://www.jetbrains.com/help/teamcity/configuring-schedule-triggers.html), or via [post-commit hook](https://www.jetbrains.com/help/teamcity/configuring-vcs-post-commit-hooks-for-teamcity.html). 125 | 126 | ## Further reading 127 | 128 | You can learn more about advanced TeamCity usage through these resources: 129 | 130 | - [Build chains and dependencies](https://www.jetbrains.com/help/teamcity/build-dependencies-setup.html) 131 | - [Remote run and pre-tested commit](https://www.jetbrains.com/help/teamcity/pre-tested-delayed-commit.html) 132 | 133 | More information is available in [TeamCity documentation](https://www.jetbrains.com/help/teamcity/teamcity-documentation.html). Follow the [TeamCity blog](https://blog.jetbrains.com/teamcity/) for the latest news. 134 | 135 | ## Summary 136 | 137 | Executing Gradle builds on CI can be set up and configured with just a handful of steps. The benefit of receiving fast feedback clearly speaks for itself. If you are not using TeamCity, no problem, many CI products tightly integrate with Gradle as a first-class citizen. -------------------------------------------------------------------------------- /docs/ci/travis-ci.md: -------------------------------------------------------------------------------- 1 | # Executing Gradle builds on Travis CI 2 | 3 | !!! tip 4 | Top engineering teams using Travis CI have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. [Register here](https://dpeuniversity.gradle.com/app/courses/ec69d0b8-9171-4969-ac3e-82dea16f87b0) for our Build Cache training session to learn how your team can achieve similar results. 5 | 6 | Building Gradle projects doesn't stop with the developer's machine. [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) has been a long-established practice for running a build for every single change committed to version control to tighten the feedback loop. 7 | 8 | In this guide, we'll discuss how to configure [Travis CI](https://travis-ci.org/) for a typical Gradle project. 9 | 10 | ## What you'll need 11 | 12 | * A text editor 13 | * A command prompt 14 | * The Java Development Kit (JDK), version 1.8 or higher 15 | 16 | ## Setup a typical project 17 | 18 | As example, this guide is going to focus on a Java-based project. More specifically, a Gradle plugin written in Java and tested with [Spek](https://www.spekframework.org/). First, we'll get the project set up on your local machine before covering the same steps on CI. 19 | 20 | Just follow these steps: 21 | 22 | ### Clone the [Gradle Site Plugin](https://github.com/gradle/gradle-site-plugin) repository 23 | 24 | ```shell 25 | $ git clone https://github.com/gradle/gradle-site-plugin.git 26 | Cloning into 'gradle-site-plugin'... 27 | $ cd gradle-site-plugin 28 | ``` 29 | 30 | ### Build the project 31 | 32 | As a developer of a Java project, you'll typically want to compile the source code, run the tests and assemble the JAR artifact. That's no different for Gradle plugins. The following command achieves exactly that: 33 | 34 | ```shell 35 | $ ./gradlew build 36 | 37 | BUILD SUCCESSFUL 38 | 14 actionable tasks: 14 executed 39 | ``` 40 | 41 | The project provides the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) as part of the repository. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. 42 | 43 | ### Build scan integration 44 | 45 | The sample project is equipped with support for generating [build scans](https://scans.gradle.com/). Running the build with the command line option `--scan` renders a link in the console. 46 | 47 | ```shell 48 | $ ./gradlew build --scan 49 | Publishing build scan... 50 | https://gradle.com/s/7mtynxxmesdio 51 | ``` 52 | 53 | The following section will describe how to build the project with the help of Travis CI. 54 | 55 | ## Configure Travis CI 56 | 57 | Travis CI is a free, cloud-based CI solution provider making it an excellent choice for open source projects. You can build any project as long as it is hosted on GitHub as a public repository. Travis CI does not provide built-in options to post-process produced artifacts of the build (e.g., host the JAR file or the HTML test reports). You will have to use external services (like S3) to [transfer the files](https://docs.travis-ci.com/user/uploading-artifacts/). 58 | 59 | ### Create the configuration file 60 | 61 | Travis CI requires you to check in a [configuration file](https://docs.travis-ci.com/user/customizing-the-build/) with your source code named `.travis.yml`. This file contains all relevant instructions for building the project. 62 | 63 | The following configuration file tells Travis CI to build a Java project with JDK 8, skip the usual [default execution step](https://docs.travis-ci.com/user/job-lifecycle/#skip-the-installation-phase), and run the Gradle build with the Wrapper. 64 | 65 | ```yaml 66 | language: java 67 | install: skip 68 | 69 | os: linux 70 | dist: trusty 71 | jdk: oraclejdk8 72 | 73 | script: 74 | - ./gradlew build --scan -s 75 | ``` 76 | 77 | Select the project from the Travis CI profile. After activating the repository from the dashboard, the project is ready to be built with every single commit. 78 | 79 | ![Enabling a project](images/travis-enable-project.png) 80 | 81 | **NOTE:** Configuring [build scans](https://scans.gradle.com/) is especially helpful on cloud CI systems like Travis CI because it has additional environment and test results information that are difficult to obtain otherwise. 82 | 83 | ### Enable caching of downloaded artifacts 84 | 85 | Gradle's dependency management mechanism resolves declared modules and their corresponding artifacts from a binary repository. Once downloaded, the files will be re-used from the cache. You need to tell Travis CI explicitly that you want to [store and use the Gradle cache and Wrapper](https://docs.travis-ci.com/user/languages/java/#caching) for successive invocations of the build. 86 | 87 | ```yaml 88 | before_cache: 89 | - rm -f $HOME/.gradle/caches/modules-2/modules-2.lock 90 | - rm -fr $HOME/.gradle/caches/*/plugin-resolution/ 91 | 92 | cache: 93 | directories: 94 | - $HOME/.gradle/caches/ 95 | - $HOME/.gradle/wrapper/ 96 | ``` 97 | 98 | ### Further reading 99 | 100 | You can learn more about advanced Travis CI usage through these resources: 101 | 102 | * [Encrypting sensitive data](https://docs.travis-ci.com/user/encryption-keys/) 103 | * [Modelling a pipeline with build stages](https://docs.travis-ci.com/user/build-stages/) 104 | 105 | ## Summary 106 | 107 | Executing Gradle builds on CI can be set up and configured with just a handful of steps. The benefit of receiving fast feedback clearly speaks for itself. If you are not using Travis CI, no problem, many CI products tightly integrate with Gradle as a first-class citizen. -------------------------------------------------------------------------------- /docs/cookie-test.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Gradle Cookbook - Cookie Test 3 | template: main.html 4 | --- 5 | 6 | Hello, world! 7 | And congrats, you found a special page where we test cookies! 8 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Gradle Cookbook 3 | template: home.html 4 | --- 5 | 6 | Hello, world! 7 | -------------------------------------------------------------------------------- /docs/integrations/README.md: -------------------------------------------------------------------------------- 1 | # Gradle for Java and JVM projects 2 | 3 | This section aggregates tips & tricks for Java and for all 4 | common JVM ecosystem integrations. 5 | Technology specific items can be found elsewhere. 6 | 7 | ## Sections 8 | 9 | - [Maven Central publishing](./maven-central/publishing.md) 10 | - [CI systems](../ci/README.md) 11 | -------------------------------------------------------------------------------- /docs/integrations/maven-central/publishing.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Publishing to Maven Central" 3 | description: > 4 | Maven Central”, is one of the most popular repositories for publishing artifacts in open source projects. 5 | You can publish your Gradle projects, too. 6 | --- 7 | 8 | # Publishing to Maven Central 9 | 10 | The [Maven Central Repository](https://central.sonatype.com/) service by Sonatype, known in the community as “Maven Central”, is one of the most popular repositories for publishing open source libraries and other distributable artifacts in the Java and Kotlin ecosystems. 11 | 12 | Many developers who use Gradle publish their open source projects to Maven Central. The publishing flow for Maven Central differs significantly from publishing to a generic Maven repository using the [Maven Publish Plugin](https://docs.gradle.org/current/userguide/publishing_maven.html). It involves additional requirements for the artifacts themselves (such as metadata files and signed JARs), as well as for the publishing process (including a staging workflow and server-side verification). Hence, this solution page provides some tips and references. 13 | 14 | ## Plugins for publishing to Maven Central 15 | 16 | As of now, there is no officially recommended plugin for publishing to Maven Central. However, a variety of community-supported plugins and tools are [available](https://plugins.gradle.org/search?term=Maven+Central) on the Gradle Plugin Portal. Below are some of the most popular options plugins, ranked by GitHub stars and having more than 10 stars: 17 | 18 | * [vanniktech/gradle-maven-publish-plugin](https://github.com/vanniktech/gradle-maven-publish-plugin) 19 | * [JReleaser](https://jreleaser.org/) 20 | * [GradleUp/nmcp](https://github.com/GradleUp/nmcp) 21 | * [deepmedia/MavenDeployer](https://github.com/deepmedia/MavenDeployer) 22 | * [DanySK/maven-central-gradle-plugin](https://plugins.gradle.org/plugin/org.danilopianini.maven-central-gradle-plugin) 23 | * [yananhub/flying-gradle-plugin](https://github.com/yananhub/flying-gradle-plugin) 24 | 25 | Note that not all listed plugins are actively maintained, and one has to choose carefully based on their use cases. See the recommendations below. 26 | 27 | ## Breaking Changes in Maven Central on June 2025 28 | 29 | As [announced](https://central.sonatype.org/news/20250326_ossrh_sunset/) by Sonatype, the [Sonatype OSS Repository Hosting service (OSSRH)](https://central.sonatype.org/publish/publish-guide/) will reach end-of-life on June 30th, 2025\. OSSRH is an old and deprecated component of the [Maven Central Repository](https://central.sonatype.com/) service. 30 | 31 | With the sunset of OSSRH, Maven Central is transitioning to a new hosting implementation, which includes a complete redesign of its APIs. As a result, Maven Central publishing plugins must be updated to remain compatible once the OSSRH compatibility layer is removed in June 2025\. 32 | 33 | We invite the plugin maintainers to update their plugins and add support for the new APIs. 34 | 35 | ### Compatible Plugins 36 | 37 | Several plugins already report compatibility with the new APIs, and new plugins have been developed specifically for the updated implementation. Among the plugins listed above, the following are known to be mostly compatible based on their changelogs: 38 | 39 | * [vanniktech/gradle-maven-publish-plugin](https://github.com/vanniktech/gradle-maven-publish-plugin) (common and base versions) 40 | * [JReleaser](https://jreleaser.org/) 41 | * [GradleUp/nmcp](https://github.com/GradleUp/nmcp) 42 | 43 | ## Choosing a plugin for Maven Central publishing 44 | 45 | Choosing the right plugin might be non-trivial, as they have different feature sets and might include different developer experiences in your particular publishing use case. For common Java and Kotlin projects that do not include custom artifacts and distributions, the following selection algorithm can be considered: 46 | 47 | 1. If you want to automate the whole release process (packaging, signing, changelog generation, etc.) in a single call and are ready to follow conventions, consider using [JReleaser](https://jreleaser.org/). 48 | 2. If you want only a publishing step that follows Maven Central conventions, use [vanniktech/gradle-maven-publish-plugin](https://github.com/vanniktech/gradle-maven-publish-plugin) in the default configuration. It can publish your Java, Android, and Kotlin libraries, including sources and documentation, to Maven Central or any other Nexus instance. 49 | 3. If you want to customize the whole publishing flow, e.g., for staging or custom artifact types, use [GradleUp/nmcp](https://github.com/GradleUp/nmcp) or [com.vanniktech.maven.publish.base](https://vanniktech.github.io/gradle-maven-publish-plugin/base/). 50 | 51 | \> DISCLAIMER: This algorithm does not represent an official endorsement by Gradle, Inc. Your mileage may vary, and there are other plugins out there. 52 | 53 | ## References 54 | 55 | * [Deploying to OSSRH / Maven Central with Gradle](https://central.sonatype.org/publish/publish-gradle/) \- official documentation page on the Maven Central Documentation site 56 | * [GSoC 2025 \- Maven Central publishing for Gradle with new APIs](https://community.gradle.org/events/gsoc/2025/maven-central-publishing-with-new-api/) \- Google Summer of Code 2025 project targeting the problem area 57 | 58 | ## Discuss 59 | 60 | To support this effort, we have created a new **\#maven-central-publishing** channel on the [Gradle Community Slack](https://slack.gradle.org/). 61 | -------------------------------------------------------------------------------- /docs/kotlin/README.md: -------------------------------------------------------------------------------- 1 | # Gradle for Kotlin 2 | 3 | Gradle is one of the most popular build tools in the Kotlin space, 4 | including classic applications, Kotlin Multiplatform, and [Android](../android/README.md). 5 | 6 | ## Official Documentation 7 | 8 | The official documentation for Kotlin development with Gradle 9 | is provided by the Kotlin Foundation on its site. 10 | You can find this documentation [here](https://kotlinlang.org/docs/gradle.html). 11 | 12 | ## Featured Recipes 13 | 14 | !!! info 15 | 16 | Work in progress, recipe contributions are [welcome](../CONTRIBUTING.md)! 17 | 18 | ## References 19 | 20 | - [Gradle & Kotlin Documentation by the Kotlin Foundation](https://kotlinlang.org/docs/gradle.html) 21 | -------------------------------------------------------------------------------- /docs/plugin-development/README.md: -------------------------------------------------------------------------------- 1 | # Gradle for Plugin Development 2 | 3 | ## Recipes 4 | 5 | - [Writing Gradle plugins in Kotlin](./kotlin-plugins.md) 6 | - [Ensuring Configuration Cache compatibility](./configuration-cache/README.md) 7 | 8 | -------------------------------------------------------------------------------- /docs/plugin-development/configuration-cache/README.md: -------------------------------------------------------------------------------- 1 | # Ensuring Configuration Cache compatibility 2 | 3 | The configuration and execution phase of builds always take the longest. 4 | You may already know about the build cache, which saves execution time by reusing outputs from past builds. 5 | Gradle's [Configuration Cache](https://docs.gradle.org/current/userguide/configuration_cache.html), 6 | introduced in 6.6 and becoming a preferred mode of execution in Gradle 10, 7 | reuses configuration results from past builds to speed up the configuration phase. 8 | 9 | If you keep an eye on [Gradle public roadmap updates](https://roadmap.gradle.org), 10 | you've probably noticed lots of improvements in Configuration Cache, and steady adoption in the ecosystem. 11 | Still, there is a lot of work to be done in the plugins. 12 | Many Gradle plugins still need to have configuration cache compatibility, and also updates might be needed in end user builds and convention plugins. 13 | For the community plugins for Gradle, 14 | we track the status on [this GitHub Issue](https://github.com/gradle/gradle/issues/13490), and any contributions are more than welcome! 15 | 16 | On this page, we focus on tips for plugins developers and contributors who want to fix Configuration Cache (CC) compatibility in their projects. 17 | 18 | ## Main Documentation 19 | 20 | For Configuration Cache adoption and troubleshooting steps, you can already find information 21 | in the main documentation: 22 | 23 | - [Troubleshooting Configuration Cache compatibility](https://docs.gradle.org/current/userguide/configuration_cache.html#config_cache:troubleshooting) 24 | - [Configuration Cache Adoption Steps](https://docs.gradle.org/current/userguide/configuration_cache.html#config_cache:adoption) 25 | - [Auto-testing configuration Cache compatibility](https://docs.gradle.org/current/userguide/configuration_cache.html#config_cache:testing) 26 | 27 | 28 | ## FAQ 29 | 30 | ### How to fix "invocation of 'Task.project' at execution time is unsupported"? 31 | 32 | In essence, you should use an alternative service that provides similar functionality. See "Using the Project object" in the [Configuration Cache documentation](https://docs.gradle.org/current/userguide/configuration_cache.html#config_cache:requirements:use_project_during_execution). See a sample [fix](https://github.com/gradle/gradle/pull/21555/files#r948986470). 33 | 34 | Also, the configuration cache serialization logic handles `Provider` specially and correctly serializes their values; use `Property` and the providers returned from `org.gradle.api.provider.ProviderFactory` to store values captured from the project or the properties. 35 | 36 | ### How to fix "cannot serialize Gradle script object references"? 37 | 38 | This problem most commonly signals that a member of the enclosing script scope, for instance, a member of the `Project` object in the case of project scripts, is being used by a task action: 39 | 40 | ```kotlin 41 | tasks.register("printProjectVersion") { 42 | doLast { 43 | println(version) // <---- Project.version captured by a task action 44 | } 45 | } 46 | ``` 47 | 48 | A common example is when the `configurations` property or a configuration object (like `runtimeClasspath`) is used by a doLast/doFirst action. Avoid accessing such objects during execution. See a [fix](https://github.com/gradle/gradle/pull/21555/files#r948983984). 49 | -------------------------------------------------------------------------------- /docs/plugin-development/kotlin-plugins.md: -------------------------------------------------------------------------------- 1 | # Writing Gradle plugins in Kotlin 2 | 3 | Kotlin has [a great Java interoperability story](https://kotlinlang.org/docs/java-to-kotlin-interop.html), making it a good language to write Gradle plugins. 4 | 5 | For complete compatibility, several aspects require extra care. This page gives an overview of the different compatibility issues and recommended setup to avoid them. 6 | 7 | ## Gradle compatibility 8 | 9 | When executing a build, Gradle [forces its own version of `kotlin-stdlib`](https://github.com/gradle/gradle/issues/16345), the embedded version. 10 | 11 | For this reason, your plugin must depend on a version of `kotlin-stdlib` that is compatible with the embedded version. 12 | 13 | Gradle publishes the embedded versions in the [Kotlin compatibility matrix](https://docs.gradle.org/current/userguide/compatibility.html#kotlin). 14 | 15 | For an example, at the time of writing, Gradle 8.10 embeds `kotlin-stdlib:1.9.24`. 16 | 17 | ### Making your code compatible with the Kotlin embedded version 18 | 19 | You can use a more recent version of the Kotlin Gradle Plugin, but you'll have to make sure not to call any 2.0 API: 20 | 21 | ```kotlin 22 | plugins { 23 | // Use latest version of the Kotlin Gradle Plugin 24 | id("org.jetbrains.kotlin.jvm").version("2.0.21") 25 | // java-gradle-plugin creates marker publications and plugin descriptors 26 | id("java-gradle-plugin") 27 | } 28 | 29 | tasks.withType().configureEach { 30 | // But make sure your plugin code only uses 1.9 APIs 31 | compilerOptions.apiVersion.set(KotlinVersion.KOTLIN_1_9) 32 | } 33 | 34 | kotlin { 35 | // Also make sure to depend on 1.9 kotlin-stdlib 36 | // See also https://youtrack.jetbrains.com/issue/KT-53462 37 | coreLibrariesVersion = "1.9.24" 38 | } 39 | ``` 40 | 41 | ### Ensuring dependencies are compatible with the Kotlin embedded version 42 | 43 | In addition to your own code, your dependencies must also use a compatible version of `kotlin-stdlib`. 44 | 45 | Because the compiler doesn't run on dependencies, `apiVersion` does not help here, you'll have to check that the dependencies do not depend on a newer version of `kotlin-stdlib`. 46 | 47 | This can be done using a custom Gradle task: 48 | 49 | ```kotlin 50 | /** 51 | * An example of a task that checks that no kotlin-stdlib > 1.9.24 is pulled 52 | * in the classpath. 53 | * Configuration cache and edge cases are left as an exercise to the reader. 54 | */ 55 | tasks.register("checkGradleCompatibility") { 56 | doLast { 57 | val root = configurations.getByName("runtimeClasspath").incoming.resolutionResult.rootComponent.get() 58 | root.dependencies.forEach { 59 | if (it is ResolvedDependencyResult) { 60 | val rdr = it 61 | val requested = rdr.requested 62 | val selected = rdr.selected 63 | if ( 64 | requested is ModuleComponentSelector 65 | && requested.group == "org.jetbrains.kotlin" 66 | && requested.module == "kotlin-stdlib" 67 | ) { 68 | 69 | val requestedVersion = requested.version 70 | val selectedVersion = selected.moduleVersion?.version 71 | check (selectedVersion == requestedVersion) { 72 | "kotlin-stdlib was upgraded to $selectedVersion" 73 | } 74 | } 75 | } 76 | } 77 | } 78 | } 79 | ``` 80 | 81 | ### Alternative #1: relocating kotlin-stdlib 82 | 83 | If the steps above are too complicated, maybe because a required dependency uses a newer version of Kotlin, or because your own plugin code requires newer Kotlin features, you can shadow a relocated version of `kotlin-stdlib` that doesn't clash with the Gradle embedded one. 84 | 85 | To do this, you can use [R8](https://github.com/GradleUp/GR8). You can read more about the process [in this dedicated blog post](https://blog.mbonnin.net/use-latest-kotlin-in-your-gradle-plugins). 86 | 87 | !!! note 88 | [Shadow](https://github.com/GradleUp/shadow/) could be an alternative, but we have found that it doesn't work reliably because [it relocates String constants as well](https://github.com/GradleUp/shadow/issues/232) 89 | 90 | ### Alternative #2: using separate classloaders 91 | 92 | Another solution if you want to use a newer `kotlin-stdlib` without using relocation is to run your code in a separate, isolated, classloader. The glue code of your plugin and initialization still has to be compatible but as soon as you switch to a new classloader, you can use any dependencies without any risk of incompatibilities. 93 | 94 | Projects such as [Gratatouille](https://github.com/GradleUp/Gratatouille) can help with that. 95 | 96 | ## Groovy interoperability 97 | 98 | Because your plugin may be used from Groovy build scripts (`build.gradle`), it is important to have Groovy compatibility in mind. 99 | 100 | ### General interoperability 101 | 102 | In general Groovy does not know anything about Kotlin. Avoid Kotlin-only features such as: 103 | 104 | - extension functions 105 | - default parameter values 106 | - function types 107 | - receivers 108 | - etc... 109 | 110 | These features may be used in extra functionality for Kotlin callers, but it is important that all the base functionality of your plugin does not require them. 111 | 112 | ### Closures 113 | 114 | Closure are an important piece of the Groovy build scripts. Every block is a closure under the hood. 115 | 116 | Because dealing with Groovy closure from Kotlin (and Java) is cumbersome, Gradle allows to use `Action` instead. For all types instantiated by Gradle (tasks, extensions, [newInstance()](https://docs.gradle.org/current/kotlin-dsl/gradle/org.gradle.api.model/-object-factory/new-instance.html), etc..), the Gradle runtime decorates all functions with a single `Action` parameter with an matching function accepting a closure ([doc](https://docs.gradle.org/current/userguide/kotlin_dsl.html#groovy_closures_from_kotlin)). 117 | 118 | For an example, the Kotlin code below: 119 | 120 | ```kotlin 121 | open class MyExtension { 122 | fun doStuff(action: Action) { 123 | // ... 124 | } 125 | } 126 | ``` 127 | 128 | can be called from groovy with a closure: 129 | 130 | ```groovy 131 | myExtension { 132 | doStuff { 133 | // This is a closure even though groovy doesn't know about Action 134 | // ... 135 | } 136 | } 137 | ``` 138 | 139 | ## Difference with `build.gradle.kts` scripts 140 | 141 | If you are used to writing `build.gradle.kts` files, you may use the `kotlin-dsl` Gradle plugin to write your plugins. 142 | 143 | `kotlin-dsl` configures the Kotlin compiler so that you can use precompiled scripts plugins and/or write similar syntax in your regular `.kt` files. 144 | 145 | The `kotlin-dsl` plugin: 146 | 147 | * applies `"java-gradle-plugin"`. 148 | * applies `kotlin-embedded` to use the same Kotlin embedded version as your Gradle distribution. 149 | * applies the `"kotlin-dsl-precompiled-script-plugins"` allowing to use `build.gradle.kts` files. 150 | * adds `gradleKotlinDsl()` to the `compileOnly` configuration. 151 | * configures the `sam-with-receiver` Kotlin compiler plugin to transform `it.` usages into `this.`. 152 | * configures the `kotlin-assignment` Kotlin compiler plugin to allow setting `Property` with the `=` operator. 153 | * sets Kotlin `apiVersion` and `languageVersion` according to Gradle [compatibility matrix](https://docs.gradle.org/current/userguide/compatibility.html#kotlin). 154 | * adds the `-Xsam-conversions=class` compiler option. 155 | * adds others compiler options for compatibility: 156 | * `-java-parameters` to support [Java 8 Parameter](https://docs.oracle.com/javase/8/docs/api/java/lang/reflect/Parameter.html) class and getting method parameters through reflection 157 | * `-Xjvm-default=all` to add link: [Default methods in interfaces](https://kotlinlang.org/docs/java-to-kotlin-interop.html#default-methods-in-interfaces) 158 | * `-Xjsr305=strict` for [increased null safety](https://kotlinlang.org/docs/java-interop.html#compiler-configuration) 159 | 160 | This is a significant departure from the baseline Kotlin configuration so be aware of the trade-offs when using `kotlin-dsl`. 161 | 162 | Also, `kotlin-dsl` targets the Kotlin embedded version of your current distribution. If you want to be compatible with lower versions of Gradle, using the `com.jetbrains.kotlin.jvm` plugin provides more flexibility. 163 | -------------------------------------------------------------------------------- /docs/preface.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "The Gradle Cookbook" 3 | description: > 4 | Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. 5 | --- 6 | 7 | Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. 8 | This is a complementary resource to the official [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html), 9 | which covers core capabilities maintained by the Gradle team. 10 | 11 | The goal of this portal is to offer solution-based documentation for end users about external integrations, 12 | including but not limited to 13 | CI/CD tools, IDEs, 14 | support for languages and frameworks, 15 | and various peripheral tools. 16 | 17 | In the Gradle Cookbook, _Gradle Build Tool_ is abbreviated _Gradle_. 18 | 19 | !!! note 20 | The Gradle Cookbook is under active development (see the roadmap item [here](https://github.com/gradle/community/issues/42)). 21 | Its structure, scope and links may change, and we're working on adding more content. 22 | Any contributions are welcome, see the [Contributor Guide](./CONTRIBUTING.md)! 23 | 24 | ## Why and How? 25 | 26 | The Gradle Build Tool ecosystem is huge, it includes many plugins, integrations, developer tools and other components. 27 | Not all of them can be covered in the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html) 28 | which represents core documentation maintained for each Gradle release. 29 | Moreover, being tied to the Gradle release contribution process and the release cycle makes it more difficult to contribute there. 30 | Maintaining documentation has been challenging for us as well, 31 | leading to many outdated pages. 32 | 33 | So, we decided to build a second resource as an extension to the Gradle User Manual, 34 | with the following in mind: 35 | 36 | - Gradle Cookbook remains an official resource under `community.gradle.org`. 37 | It is not a second-class citizen, just another structure that is not tied to the Gradle release cycle 38 | - Pages should be focused on offering solutions to end users for particular use cases, 39 | hence the _Cookbook_ 40 | - We follow the Wiki-alike collaboration style, 41 | with a lower barrier to contribute than `gradle/gradle`. 42 | Some sections can get explicit maintainers/reviewers over time. 43 | - We use Documentation-as-Code, with simple Markdown or Asciidoc files used as a source 44 | - Minimizing duplication. 45 | We can include documentation from other sources under the [Gradle GitHub organization](https://github.com/gradle/) 46 | 47 | ## Trademark Notice 48 | 49 | Gradle and the Gradlephant logo (the "Gradle Marks") are registered trademarks of Gradle, Inc. and/or its subsidiaries. 50 | Use of the Gradle Marks the Gradle Cookbook pages is for identification purposes only and does not imply sponsorship or endorsement by Gradle, Inc. 51 | In the Gradle Cookbook, "Gradle" typically means "Gradle Build Tool" and does not reference Gradle Inc. and/or its subsidiaries. 52 | 53 | See the [Gradle Branding Guidelines](https://gradle.com/brand/) for more information about 54 | trademark usage and the approval process. 55 | 56 | ## References 57 | 58 | - [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html) 59 | - [Other Documentation Locations](https://community.gradle.org/contributing/documentation) -------------------------------------------------------------------------------- /docs/troubleshooting/README.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting Gradle 2 | 3 | Tools, tips and tricks for troubleshooting issues with Gradle. 4 | 5 | !!! info 6 | 7 | Work in progress, recipe contributions are [welcome](../CONTRIBUTING.md)! 8 | 9 | ## References 10 | 11 | - [Official Troubleshooting Guide](https://docs.gradle.org/current/userguide/troubleshooting.html) 12 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Gradle Cookbook 2 | site_author: Gradle Contributors 3 | site_description: >- 4 | Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. 5 | This is a complementary resource to the official Gradle User Manual. 6 | copyright: > 7 | Copyright © 2025 - All contributors to the repository and included components. 8 | Gradle®, Develocity®, Build Scan®, and the Gradlephant logo are registered trademarks of Gradle, Inc. 9 | On this resource, "Gradle" typically means "Gradle Build Tool" and does not reference Gradle, Inc. and/or its subsidiaries. 10 | docs_dir: docs 11 | repo_url: https://github.com/gradle/cookbook 12 | repo_name: Gradle Cookbook 13 | edit_uri: edit/main/docs/ 14 | site_url: https://cookbook.gradle.org 15 | 16 | # Build 17 | site_dir: _site 18 | 19 | nav: 20 | - Overview: 21 | - preface.md 22 | - chapters.md 23 | - Contributing: CONTRIBUTING.md 24 | - Integrations: 25 | - Overview: integrations/README.md 26 | - Maven Central Publishing: integrations/maven-central/publishing.md 27 | - Gradle and CI: 28 | - Summary: ci/README.md 29 | - Jenkins: ci/jenkins.md 30 | - TeamCity: ci/teamcity.md 31 | - GitHub Actions: ci/github-actions.md 32 | - GitLab CI: ci/gitlab-ci.md 33 | - Travis CI: ci/travis-ci.md 34 | - Gradle for Kotlin: kotlin/README.md 35 | - Gradle for Android: android/README.md 36 | - Troubleshooting Gradle: troubleshooting/README.md 37 | - Plugin Development: 38 | - Summary: plugin-development/README.md 39 | - Kotlin plugin development: plugin-development/kotlin-plugins.md 40 | - Ensuring Configuration Cache compatibility: plugin-development/configuration-cache/ 41 | 42 | # Theme 43 | theme: 44 | name: material 45 | custom_dir: overrides/ 46 | highlightjs: true 47 | features: 48 | - announce.dismiss 49 | - content.action.edit 50 | - content.action.view 51 | - content.code.annotate 52 | - content.code.copy 53 | - content.code.select 54 | - content.tabs.link 55 | - content.tooltips 56 | # - header.autohide 57 | # - navigation.expand 58 | - navigation.footer 59 | # NOT compatible qith toc.integrate 60 | # - navigation.indexes 61 | - navigation.path 62 | # - navigation.instant 63 | # - navigation.instant.prefetch 64 | # - navigation.instant.progress 65 | # - navigation.prune 66 | - navigation.sections 67 | - navigation.expand 68 | - navigation.tabs 69 | # - navigation.tabs.sticky 70 | - navigation.top 71 | - navigation.tracking 72 | - search.highlight 73 | - search.share 74 | - search.suggest 75 | - toc.follow 76 | - toc.integrate 77 | palette: 78 | - scheme: default 79 | media: "(prefers-color-scheme: light)" 80 | primary: custom 81 | toggle: 82 | icon: material/brightness-7 83 | name: Switch to dark mode 84 | 85 | - scheme: slate 86 | media: "(prefers-color-scheme: dark)" 87 | primary: custom 88 | toggle: 89 | icon: material/brightness-4 90 | name: Switch to light mode 91 | font: 92 | # TODO: use the site's scheme 93 | # text: Lato Lite 94 | code: Roboto Mono 95 | favicon: assets/images/logos/gradle.svg 96 | logo: assets/images/logos/gradle.svg 97 | icon: 98 | repo: fontawesome/brands/github 99 | 100 | 101 | extra_css: 102 | - assets/css/gradle.css 103 | 104 | extra: 105 | social: 106 | - icon: fontawesome/brands/slack 107 | link: https://gradle.org/slack-invite 108 | name: Slack 109 | - icon: fontawesome/brands/github 110 | link: https://github.com/gradle 111 | name: GitHub 112 | - icon: fontawesome/brands/x-twitter 113 | link: https://twitter.com/gradle 114 | name: Twitter/X 115 | - icon: fontawesome/brands/linkedin 116 | link: https://www.linkedin.com/company/gradle 117 | name: LinkedIn 118 | - icon: fontawesome/brands/mastodon 119 | link: https://mastodon.social/@Gradle 120 | name: Mastodon 121 | analytics: 122 | provider: custom 123 | 124 | 125 | 126 | plugins: 127 | - search 128 | - autorefs 129 | # FIXME: Collision on GitHub Actions, to be fixed later 130 | # - macros 131 | - mkdocs-pdf 132 | # OpenGraphs 133 | - social: 134 | cards_layout_options: 135 | background_color: "#010002" 136 | font_family: Lato 137 | # - group: 138 | # enabled: !ENV [FULL_BUILD, true] 139 | # plugins: 140 | # - multirepo: 141 | # cleanup: false 142 | # keep_docs_dir: true 143 | # nav_repos: 144 | # - name: github-actions 145 | # import_url: 'https://github.com/gradle/actions?branch=main&edit_uri=/blob/main/' 146 | # imports: [ "README.md", "*" ] 147 | 148 | - git-revision-date-localized 149 | - git-committers: 150 | repository: gradle/cookbook 151 | branch: main 152 | - mkdocs-nav-weight: 153 | # Index/README go first in folder includes 154 | index_weight: -10 155 | 156 | - with-pdf: 157 | enabled_if_env: BUILD_PDF 158 | output_path: pdf/cookbook.pdf 159 | author: Gradle Contributors 160 | # FIXME: Needs rendering style to include the trademark notice & Co into the header 161 | copyright: > 162 | Copyright © 2024 - All contributors to the repository and included components. 163 | cover: true 164 | cover_title: The Gradle Cookbook 165 | cover_subtitle: Open Source Recipes for Gradle Build Tool 166 | cover_logo: https://gradle.com/wp-content/themes/fuel/assets/img/branding/gradle-elephant-icon-gradient.svg 167 | back_cover: true 168 | toc_title: Table of Contents 169 | toc_level: 3 170 | show_anchors: true 171 | 172 | # Markdown 173 | markdown_extensions: 174 | - pymdownx.highlight: 175 | anchor_linenums: true 176 | line_spans: __span 177 | pygments_lang_class: true 178 | - pymdownx.details 179 | - pymdownx.inlinehilite 180 | - pymdownx.snippets 181 | - pymdownx.superfences 182 | - pymdownx.tabbed: 183 | alternate_style: true 184 | - toc: 185 | permalink: '#' 186 | - admonition 187 | - attr_list 188 | - pymdownx.emoji: 189 | emoji_index: !!python/name:material.extensions.emoji.twemoji 190 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 191 | - pymdownx.tasklist: 192 | custom_checkbox: true 193 | -------------------------------------------------------------------------------- /overrides/home.html: -------------------------------------------------------------------------------- 1 | {% extends "main.html" %} 2 | {% block tabs %} 3 | {{ super() }} 4 | 5 | 6 | 85 | 86 |
87 |
88 |
89 |
90 | Gradle Logo 91 |
92 |
93 |

Gradle Cookbook

94 |

{{ config.site_description }} Contributions are welcome!

95 |
96 |
97 | 98 | Overview 99 | 100 | 101 | Chapters 102 | 103 |
104 |
105 |
106 |
107 | {% endblock %} 108 | 109 | {% block content %}{% endblock %} 110 | 111 | {% block footer %} 112 | {{ super() }} 113 | {% endblock %} 114 | -------------------------------------------------------------------------------- /overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | {% block announce %} 4 | {% endblock %} 5 | 6 | {% block scripts %} 7 | {{ super() }} 8 | {% endblock %} 9 | 10 | {% block footer %} 11 | 12 | 13 | 14 | {{ super() }} 15 | {% endblock %} 16 | -------------------------------------------------------------------------------- /overrides/partials/integrations/analytics/custom.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 7 | 8 | --------------------------------------------------------------------------------