diff options
Diffstat (limited to 'doc/user/packages')
-rw-r--r-- | doc/user/packages/workflows/build_packages.md | 504 |
1 files changed, 504 insertions, 0 deletions
diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md new file mode 100644 index 00000000000..063217f0ad7 --- /dev/null +++ b/doc/user/packages/workflows/build_packages.md @@ -0,0 +1,504 @@ +--- +stage: Package +group: Package Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Build packages + +Learn how to install and build packages different package formats. + +- [Composer](#composer) +- [Conan](#conan) +- [Maven](#maven) +- [Gradle](#gradle) +- [npm](#npm) +- [Yarn](#yarn) +- [NuGet](#nuget) +- [PyPI](#pypi) + +## Composer + +1. Create a directory called `my-composer-package` and change to that directory: + + ```shell + mkdir my-composer-package && cd my-composer-package + ``` + +1. Run [`composer init`](https://getcomposer.org/doc/03-cli.md#init) and answer the prompts. + + For namespace, enter your unique [namespace](../../../user/namespace/index.md), like your GitLab username or group name. + + A file called `composer.json` is created: + + ```json + { + "name": "<namespace>/composer-test", + "description": "Library XY", + "type": "library", + "license": "GPL-3.0-only", + "authors": [ + { + "name": "John Doe", + "email": "john@example.com" + } + ], + "require": {} + } + ``` + +## Conan + +### Install Conan + +Download the Conan package manager to your local development environment by +following the instructions at [conan.io](https://conan.io/downloads.html). + +When installation is complete, verify you can use Conan in your terminal by +running: + +```shell +conan --version +``` + +The Conan version is printed in the output: + +```plaintext +Conan version 1.20.5 +``` + +### Install CMake + +When you develop with C++ and Conan, you can select from many available +compilers. This example uses the CMake build system generator. + +To install CMake: + +- For Mac, use [Homebrew](https://brew.sh/) and run `brew install cmake`. +- For other operating systems, follow the instructions at [cmake.org](https://cmake.org/install/). + +When installation is complete, verify you can use CMake in your terminal by +running: + +```shell +cmake --version +``` + +The CMake version is printed in the output. + +### Create a project + +To test the Package Registry, you need a C++ project. If you don't already have +one, you can clone the Conan [hello world starter project](https://github.com/conan-io/hello). + +### Build a Conan package + +To build a package: + +1. Open a terminal and navigate to your project's root folder. +1. Generate a new recipe by running `conan new` with a package name and version: + + ```shell + conan new Hello/0.1 -t + ``` + +1. Create a package for the recipe by running `conan create` with the Conan user + and channel: + + ```shell + conan create . mycompany/beta + ``` + + NOTE: + If you use an [instance remote](../conan_repository/index.md#add-a-remote-for-your-instance), you must + follow a specific [naming convention](../conan_repository/index.md#package-recipe-naming-convention-for-instance-remotes). + +A package with the recipe `Hello/0.1@mycompany/beta` is created. + +For more details about creating and managing Conan packages, see the +[Conan documentation](https://docs.conan.io/en/latest/creating_packages.html). + +## Maven + +### Install Maven + +The required minimum versions are: + +- Java 11.0.5+ +- Maven 3.6+ + +Follow the instructions at [maven.apache.org](https://maven.apache.org/install.html) +to download and install Maven for your local development environment. After +installation is complete, verify you can use Maven in your terminal by running: + +```shell +mvn --version +``` + +The output should be similar to: + +```shell +Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T20:00:29+01:00) +Maven home: /Users/<your_user>/apache-maven-3.6.1 +Java version: 12.0.2, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/Contents/Home +Default locale: en_GB, platform encoding: UTF-8 +OS name: "mac os x", version: "10.15.2", arch: "x86_64", family: "mac" +``` + +### Build a Maven package + +1. Open your terminal and create a directory to store the project. +1. From the new directory, run this Maven command to initialize a new package: + + ```shell + mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false + ``` + + The arguments are: + + - `DgroupId`: A unique string that identifies your package. Follow + the [Maven naming conventions](https://maven.apache.org/guides/mini/guide-naming-conventions.html). + - `DartifactId`: The name of the `JAR`, appended to the end of the `DgroupId`. + - `DarchetypeArtifactId`: The archetype used to create the initial structure of + the project. + - `DinteractiveMode`: Create the project using batch mode (optional). + +This message indicates that the project was set up successfully: + +```shell +... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 3.429 s +[INFO] Finished at: 2020-01-28T11:47:04Z +[INFO] ------------------------------------------------------------------------ +``` + +In the folder where you ran the command, a new directory should be displayed. +The directory name should match the `DartifactId` parameter, which in this case, +is `my-project`. + +## Gradle + +### Install Gradle + +If you want to create a new Gradle project, you must install Gradle. Follow +instructions at [gradle.org](https://gradle.org/install/) to download and install +Gradle for your local development environment. + +In your terminal, verify you can use Gradle by running: + +```shell +gradle -version +``` + +To use an existing Gradle project, in the project directory, +on Linux execute `gradlew`, or on Windows execute `gradlew.bat`. + +The output should be similar to: + +```plaintext +------------------------------------------------------------ +Gradle 6.0.1 +------------------------------------------------------------ + +Build time: 2019-11-18 20:25:01 UTC +Revision: fad121066a68c4701acd362daf4287a7c309a0f5 + +Kotlin: 1.3.50 +Groovy: 2.5.8 +Ant: Apache Ant(TM) version 1.10.7 compiled on September 1 2019 +JVM: 11.0.5 (Oracle Corporation 11.0.5+10) +OS: Windows 10 10.0 amd64 +``` + +### Create a package + +1. Open your terminal and create a directory to store the project. +1. From this new directory, run this command to initialize a new package: + + ```shell + gradle init + ``` + + The output should be: + + ```plaintext + Select type of project to generate: + 1: basic + 2: application + 3: library + 4: Gradle plugin + Enter selection (default: basic) [1..4] + ``` + +1. Enter `3` to create a new Library project. The output should be: + + ```plaintext + Select implementation language: + 1: C++ + 2: Groovy + 3: Java + 4: Kotlin + 5: Scala + 6: Swift + ``` + +1. Enter `3` to create a new Java Library project. The output should be: + + ```plaintext + Select build script DSL: + 1: Groovy + 2: Kotlin + Enter selection (default: Groovy) [1..2] + ``` + +1. Enter `1` to create a new Java Library project that is described in Groovy DSL, or `2` to create one that is described in Kotlin DSL. The output should be: + + ```plaintext + Select test framework: + 1: JUnit 4 + 2: TestNG + 3: Spock + 4: JUnit Jupiter + ``` + +1. Enter `1` to initialize the project with JUnit 4 testing libraries. The output should be: + + ```plaintext + Project name (default: test): + ``` + +1. Enter a project name or press <kbd>Enter</kbd> to use the directory name as project name. + +## npm + +### Install npm + +Install Node.js and npm in your local development environment by following +the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/). + +When installation is complete, verify you can use npm in your terminal by +running: + +```shell +npm --version +``` + +The npm version is shown in the output: + +```plaintext +6.10.3 +``` + +### Create an npm package + +1. Create an empty directory. +1. Go to the directory and initialize an empty package by running: + + ```shell + npm init + ``` + +1. Enter responses to the questions. Ensure the **package name** follows + the [naming convention](../npm_registry/index.md#package-naming-convention) and is scoped to the project or group where the registry exists. + +## Yarn + +### Install Yarn + +As an alternative to npm, you can install Yarn in your local environment by following the +instructions at [classic.yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). + +When installation is complete, verify you can use Yarn in your terminal by +running: + +```shell +yarn --version +``` + +The Yarn version is shown in the output: + +```plaintext +1.19.1 +``` + +### Create a package + +1. Create an empty directory. +1. Go to the directory and initialize an empty package by running: + + ```shell + yarn init + ``` + +1. Enter responses to the questions. Ensure the **package name** follows + the [naming convention](../npm_registry/index.md#package-naming-convention) and is scoped to the + project or group where the registry exists. + +A `package.json` file is created. + +## NuGet + +### Install NuGet + +Follow the instructions from [https://learn.microsoft.com/en-us/nuget/install-nuget-client-tools] Microsoft to install NuGet. If you have +[Visual Studio](https://visualstudio.microsoft.com/vs/), NuGet is +probably already installed. + +Verify that the [NuGet CLI](https://www.nuget.org/) is installed by running: + +```shell +nuget help +``` + +The output should be similar to: + +```plaintext +NuGet Version: 5.1.0.6013 +usage: NuGet <command> [args] [options] +Type 'NuGet help <command>' for help on a specific command. + +Available commands: + +[output truncated] +``` + +## PyPI + +### Install pip and twine + +Install a recent version of [pip](https://pypi.org/project/pip/) and +[twine](https://pypi.org/project/twine/). + +### Create a project + +Create a test project. + +1. Open your terminal. +1. Create a directory called `MyPyPiPackage`, and then go to that directory: + + ```shell + mkdir MyPyPiPackage && cd MyPyPiPackage + ``` + +1. Create another directory and go to it: + + ```shell + mkdir mypypipackage && cd mypypipackage + ``` + +1. Create the required files in this directory: + + ```shell + touch __init__.py + touch greet.py + ``` + +1. Open the `greet.py` file, and then add: + + ```python + def SayHello(): + print("Hello from MyPyPiPackage") + return + ``` + +1. Open the `__init__.py` file, and then add: + + ```python + from .greet import SayHello + ``` + +1. To test the code, in your `MyPyPiPackage` directory, start the Python prompt. + + ```shell + python + ``` + +1. Run this command: + + ```python + >>> from mypypipackage import SayHello + >>> SayHello() + ``` + +A message indicates that the project was set up successfully: + +```plaintext +Python 3.8.2 (v3.8.2:7b3ab5921f, Feb 24 2020, 17:52:18) +[Clang 6.0 (clang-600.0.57)] on darwin +Type "help", "copyright", "credits" or "license" for more information. +>>> from mypypipackage import SayHello +>>> SayHello() +Hello from MyPyPiPackage +``` + +### Create a PyPI package + +After you create a project, you can create a package. + +1. In your terminal, go to the `MyPyPiPackage` directory. +1. Create a `pyproject.toml` file: + + ```shell + touch pyproject.toml + ``` + + This file contains all the information about the package. For more information + about this file, see [creating `pyproject.toml`](https://packaging.python.org/en/latest/tutorials/packaging-projects/#creating-pyproject-toml). + Because GitLab identifies packages based on + [Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), + ensure your package name meets these requirements. See the [installation section](../pypi_repository/index.md#authenticate-with-a-ci-job-token) + for details. + +1. Open the `pyproject.toml` file, and then add basic information: + + ```toml + [build-system] + requires = ["setuptools>=61.0"] + build-backend = "setuptools.build_meta" + + [project] + name = "mypypipackage" + version = "0.0.1" + authors = [ + { name="Example Author", email="author@example.com" }, + ] + description = "A small example package" + requires-python = ">=3.7" + classifiers = [ + "Programming Language :: Python :: 3", + "Operating System :: OS Independent", + ] + + [tool.setuptools.packages] + find = {} + ``` + +1. Save the file. +1. Install the package build library: + + ```shell + pip install build + ``` + +1. Build the package: + + ```shell + python -m build + ``` + +The output should be visible in a newly-created `dist` folder: + +```shell +ls dist +``` + +The output should appear similar to the following: + +```plaintext +mypypipackage-0.0.1-py3-none-any.whl mypypipackage-0.0.1.tar.gz +``` + +The package is now ready to be published to the Package Registry. |