vcpkg/docs/maintainers/vcpkg_from_gitlab.md

# vcpkg_from_gitlab

Download and extract a project from Gitlab instances. Enables support for `install --head`.

## Usage:
```cmake
vcpkg_from_gitlab(
    GITLAB_URL <https://gitlab.com>
    OUT_SOURCE_PATH <SOURCE_PATH>
    REPO <gitlab-org/gitlab-ce>
    [REF <v10.7.3>]
    [SHA512 <45d0d7f8cc350...>]
    [HEAD_REF <master>]
    [PATCHES <patch1.patch> <patch2.patch>...]
)
```

## Parameters:

### GITLAB_URL
The URL of the Gitlab instance to use.

### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.

This should be set to `SOURCE_PATH` by convention.

### REPO
The organization or user plus the repository name on the Gitlab instance.

### REF
A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**

For repositories without official releases, this can be set to the full commit id of the current latest master.

If `REF` is specified, `SHA512` must also be specified.

### SHA512
The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).
The REPO_NAME variable is parsed from the value of REPO.

This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.

### HEAD_REF
The unstable git commit-ish (ideally a branch) to pull for `--head` builds.

For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.

### PATCHES
A list of patches to be applied to the extracted sources.

Relative paths are based on the port directory.

## Notes:
At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.

This exports the `VCPKG_HEAD_VERSION` variable during head builds.

## Examples:

* [tiny-process-library](https://github.com/Microsoft/vcpkg/blob/master/ports/tiny-process-library/portfile.cmake#L3)

## Source
[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)
[docs] Add docs for vcpkg_from_gitlab() 2018-08-08 19:16:15 +08:00			`# vcpkg_from_gitlab`

			Download and extract a project from Gitlab instances. Enables support for `install --head`.

			`## Usage:`
			```cmake
			`vcpkg_from_gitlab(`
[docs] Fix GITLAB_INSTANCE-> GITLAB_URL 2018-08-08 20:25:20 +08:00			`GITLAB_URL <https://gitlab.com>`
[docs] Add docs for vcpkg_from_gitlab() 2018-08-08 19:16:15 +08:00			`OUT_SOURCE_PATH <SOURCE_PATH>`
			`REPO <gitlab-org/gitlab-ce>`
			`[REF <v10.7.3>]`
			`[SHA512 <45d0d7f8cc350...>]`
			`[HEAD_REF <master>]`
xalan-c: Install headers correctly (#4565) * Add SKIP_CLEAN option to vcpkg_install_msbuild Also add vcpkg_clean_msbuild function to factor out clean logic and allow re-use in portfiles. * xalan-c: Correct header globbing * vcpkg_install_msbuild: SKIP_CLEAN documentation correction * [xalan-c] Add explicit check for localmsgindex header. [docs] Regenerate 2018-10-26 03:34:45 +08:00			`[PATCHES <patch1.patch> <patch2.patch>...]`
[docs] Add docs for vcpkg_from_gitlab() 2018-08-08 19:16:15 +08:00			`)`
			```

			`## Parameters:`

			`### GITLAB_URL`
			`The URL of the Gitlab instance to use.`

			`### OUT_SOURCE_PATH`
			`Specifies the out-variable that will contain the extracted location.`

			This should be set to `SOURCE_PATH` by convention.

			`### REPO`
			`The organization or user plus the repository name on the Gitlab instance.`

			`### REF`
			`A stable git commit-ish (ideally a tag) that will not change contents. This should not be a branch.`

			`For repositories without official releases, this can be set to the full commit id of the current latest master.`

			If `REF` is specified, `SHA512` must also be specified.

			`### SHA512`
			`The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).`
			`The REPO_NAME variable is parsed from the value of REPO.`

			This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.

			`### HEAD_REF`
			The unstable git commit-ish (ideally a branch) to pull for `--head` builds.

			For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.

xalan-c: Install headers correctly (#4565) * Add SKIP_CLEAN option to vcpkg_install_msbuild Also add vcpkg_clean_msbuild function to factor out clean logic and allow re-use in portfiles. * xalan-c: Correct header globbing * vcpkg_install_msbuild: SKIP_CLEAN documentation correction * [xalan-c] Add explicit check for localmsgindex header. [docs] Regenerate 2018-10-26 03:34:45 +08:00			`### PATCHES`
			`A list of patches to be applied to the extracted sources.`

			`Relative paths are based on the port directory.`

[docs] Add docs for vcpkg_from_gitlab() 2018-08-08 19:16:15 +08:00			`## Notes:`
			At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.

			This exports the `VCPKG_HEAD_VERSION` variable during head builds.

[docs] Add vcpkg functions usage examples (#5639) 2019-03-12 08:29:37 +08:00			`## Examples:`

			`* [tiny-process-library](https://github.com/Microsoft/vcpkg/blob/master/ports/tiny-process-library/portfile.cmake#L3)`
[docs] Add docs for vcpkg_from_gitlab() 2018-08-08 19:16:15 +08:00
			`## Source`
[docs] Add vcpkg functions usage examples (#5639) 2019-03-12 08:29:37 +08:00			`[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)`