Skip to content

Commit b572d02

Browse files
agriyakhetarpalagriyakhetarpal
committed
🚛 Move supported platforms docs to new page
1 parent 05d8437 commit b572d02

File tree

2 files changed

+108
-112
lines changed

2 files changed

+108
-112
lines changed

‎docs/content/_index.md‎

Lines changed: 0 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -114,114 +114,3 @@ It is a great idea to use [`pipx`](https://github.com/pypa/pipx) to install or u
114114
Please refer to the [`pipx` documentation](https://pipx.pypa.io/stable/) for more information.
115115

116116
For more information on using Hugo and its command-line interface, please refer to the [Hugo documentation](https://gohugo.io/documentation/) and the [Hugo CLI documentation](https://gohugo.io/commands/).
117-
118-
### Supported platforms
119-
120-
A subset of the platforms supported by Hugo itself are supported by these wheels for `hugo` via `hugo-python-distributions`. The plan is to support as many platforms as possible with Python wheels and platform tags. Please refer to the following table for a list of supported platforms and architectures:
121-
122-
| Platform | Architecture | Support |
123-
| -------- | --------------- | ------------------------------- |
124-
| macOS | x86_64 (Intel) | ✅ |
125-
| macOS | arm64 (Silicon) | ✅ |
126-
| Linux | amd64 | ✅ |
127-
| Linux | arm64 | ✅ |
128-
| Windows | x86_64 | ✅ |
129-
| Windows | arm64 | 💡 Experimental support [^1] |
130-
| Windows | x86 | 💡 Experimental support [^1] |
131-
| DragonFlyBSD | amd64 | ❌ Will not receive support[^2] |
132-
| FreeBSD | amd64 | ❌ Will not receive support[^2] |
133-
| OpenBSD | amd64 | ❌ Will not receive support[^2] |
134-
| NetBSD | amd64 | ❌ Will not receive support[^2] |
135-
| Solaris | amd64 | ❌ Will not receive support[^2] |
136-
137-
[^1]: Support for 32-bit (i686) and arm64 architectures on Windows is made possible through the use of the [Zig compiler toolchain](https://ziglang.org/) that uses the LLVM ecosystem. These wheels are experimental owing to the use of `cibuildwheel` and cross-compilation and may not be stable or reliable for all use cases, and are not officially supported by the Hugo project at this time. Please refer to the [Building from source](#building-from-source) section for more information on how to build Hugo for these platforms and architectures, since these wheels are not currently pushed to PyPI for general availability – however, they are tested regularly in CI. If you need support for these platforms, please consider building from source or through a CI provider.
138-
139-
[^2]: Support for these platforms is not possible to include because of i. the lack of resources to test and build for them and ii. the lack of support for these platform specifications in Python packaging standards and tooling. If you need support for these platforms, please consider downloading the [official Hugo binaries](https://github.com/gohugoio/hugo/releases).
140-
141-
#### Cross-compiling for different architectures
142-
143-
{{< callout type="warning" >}}
144-
Cross-compilation is experimental and may not be stable or reliable for all use cases. If you encounter any issues with cross-compilation, please feel free to [open an issue](https://github.com/agriyakhetarpal/hugo-python-distributions/issues/new).
145-
{{</ callout >}}
146-
147-
This project is capable of cross-compiling Hugo binaries for various platforms and architectures and it can be used as follows. Cross-compilation is provided for the following platforms:
148-
149-
1. macOS for the `arm64` and `amd64` architectures via the Xcode toolchain,
150-
2. Linux for the `arm64` and `amd64` architectures via the Zig toolchain, and
151-
3. Windows for the `arm64`, and `x86` architectures via the Zig toolchain.
152-
153-
Please refer to the examples below for more information on how to cross-compile Hugo for different architectures:
154-
155-
##### macOS
156-
157-
Say, on an Intel-based (x86_64) macOS machine:
158-
159-
```bash
160-
export GOARCH="arm64"
161-
pip install . # or pip install -e .
162-
```
163-
164-
This will build a macOS `arm64` binary distribution of Hugo that can be used on Apple Silicon-based (`arm64`) macOS machines. To build a binary distribution for the _target_ Intel-based (`x86_64`) macOS platform on the _host_ Apple Silicon-based (`arm64`) macOS machine, you can use the following command:
165-
166-
```bash
167-
export GOARCH="amd64"
168-
pip install . # or pip install -e .
169-
```
170-
171-
##### Linux
172-
173-
First, install [Zig](https://ziglang.org/download/) on your Linux machine, and set these environment variables prior to installing the package:
174-
175-
Say, on an `amd64` Linux machine:
176-
177-
```bash
178-
export CC="zig cc -target aarch64-linux-gnu"
179-
export CXX="zig c++ -target aarch64-linux-gnu"
180-
export GOARCH="arm64"
181-
pip install . # or pip install -e .
182-
```
183-
184-
will cross-compile a Linux arm64 binary distribution of Hugo that can be used on the targeted arm64 Linux machines. To build a binary distribution for the _target_ `amd64` Linux platform on the _host_ `arm64` Linux machine, set the targets differently:
185-
186-
```bash
187-
export CC="zig cc -target x86_64-linux-gnu"
188-
export CXX="zig c++ -target x86_64-linux-gnu"
189-
export GOARCH="amd64"
190-
pip install . # or pip install -e .
191-
```
192-
193-
This creates dynamic linkage for the built Hugo binary with a system-provided GLIBC. If you wish to statically link the binary with MUSL, change the `CC` and `CXX` environment variables as follows:
194-
195-
```bash
196-
export CC="zig cc -target x86_64-linux-musl"
197-
export CXX="zig c++ -target x86_64-linux-musl"
198-
```
199-
200-
Linkage against MUSL is not tested in CI at this time, but it should work in theory. The official Hugo binaries do not link against MUSL for a variety of reasons including but not limited to the size of the binary and the popularity of the GLIBC C standard library and its conventions.
201-
202-
##### Windows
203-
204-
First, install [Zig](https://ziglang.org/download/) on your Windows machine, and set these environment variables prior to installing the package:
205-
206-
Say, on an `amd64` Windows machine:
207-
208-
```bash
209-
set CC="zig cc -target aarch64-windows-gnu"
210-
set CXX="zig c++ -target aarch64-windows-gnu"
211-
set GOARCH="arm64"
212-
pip install . # or pip install -e .
213-
```
214-
215-
will cross-compile a Windows `arm64` binary distribution of Hugo that can be used on the targeted `arm64` Windows machines (note the use of `set` instead of `export` on Windows), and so on for the `x86` architecture:
216-
217-
```bash
218-
set CC="zig cc -target x86-windows-gnu"
219-
set CXX="zig c++ -target x86-windows-gnu"
220-
set GOARCH="386"
221-
pip install . # or pip install -e .
222-
```
223-
224-
For a list of supported distributions for Go, please run the `go tool dist list` command on your system. For a list of supported targets for Zig, please refer to the [Zig documentation](https://ziglang.org/documentation/) for more information or run the `zig targets` command on your system.
225-
226-
> [!TIP]
227-
> Cross-compilation for a target platform and architecture from a different host platform and architecture is also possible, but it remains largely untested at this time. Currently, the [Zig compiler toolchain](https://ziglang.org/) is known to work for cross-platform, cross-architecture compilation.

‎docs/content/supported-platforms.md‎

Lines changed: 108 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,111 @@ draft = false
55
toc = true
66
+++
77

8-
Stub content for supported platforms
8+
A subset of the platforms supported by Hugo itself are supported by these wheels for `hugo` via `hugo-python-distributions`. The plan is to support as many platforms as possible with Python wheels and platform tags. Please refer to the following table for a list of supported platforms and architectures:
9+
10+
| Platform | Architecture | Support |
11+
| -------- | --------------- | ------------------------------- |
12+
| macOS | x86_64 (Intel) | ✅ |
13+
| macOS | arm64 (Silicon) | ✅ |
14+
| Linux | amd64 | ✅ |
15+
| Linux | arm64 | ✅ |
16+
| Windows | x86_64 | ✅ |
17+
| Windows | arm64 | 💡 Experimental support [^1] |
18+
| Windows | x86 | 💡 Experimental support [^1] |
19+
| DragonFlyBSD | amd64 | ❌ Will not receive support[^2] |
20+
| FreeBSD | amd64 | ❌ Will not receive support[^2] |
21+
| OpenBSD | amd64 | ❌ Will not receive support[^2] |
22+
| NetBSD | amd64 | ❌ Will not receive support[^2] |
23+
| Solaris | amd64 | ❌ Will not receive support[^2] |
24+
25+
[^1]: Support for 32-bit (i686) and arm64 architectures on Windows is made possible through the use of the [Zig compiler toolchain](https://ziglang.org/) that uses the LLVM ecosystem. These wheels are experimental owing to the use of `cibuildwheel` and cross-compilation and may not be stable or reliable for all use cases, and are not officially supported by the Hugo project at this time. Please refer to the [Building from source](#building-from-source) section for more information on how to build Hugo for these platforms and architectures, since these wheels are not currently pushed to PyPI for general availability – however, they are tested regularly in CI. If you need support for these platforms, please consider building from source or through a CI provider.
26+
27+
[^2]: Support for these platforms is not possible to include because of i. the lack of resources to test and build for them and ii. the lack of support for these platform specifications in Python packaging standards and tooling. If you need support for these platforms, please consider downloading the [official Hugo binaries](https://github.com/gohugoio/hugo/releases).
28+
29+
#### Cross-compiling for different architectures
30+
31+
{{< callout type="warning" >}}
32+
Cross-compilation is experimental and may not be stable or reliable for all use cases. If you encounter any issues with cross-compilation, please feel free to [open an issue](https://github.com/agriyakhetarpal/hugo-python-distributions/issues/new).
33+
{{</ callout >}}
34+
35+
This project is capable of cross-compiling Hugo binaries for various platforms and architectures and it can be used as follows. Cross-compilation is provided for the following platforms:
36+
37+
1. macOS for the `arm64` and `amd64` architectures via the Xcode toolchain,
38+
2. Linux for the `arm64` and `amd64` architectures via the Zig toolchain, and
39+
3. Windows for the `arm64`, and `x86` architectures via the Zig toolchain.
40+
41+
Please refer to the examples below for more information on how to cross-compile Hugo for different architectures:
42+
43+
##### macOS
44+
45+
Say, on an Intel-based (x86_64) macOS machine:
46+
47+
```bash
48+
export GOARCH="arm64"
49+
pip install . # or pip install -e .
50+
```
51+
52+
This will build a macOS `arm64` binary distribution of Hugo that can be used on Apple Silicon-based (`arm64`) macOS machines. To build a binary distribution for the _target_ Intel-based (`x86_64`) macOS platform on the _host_ Apple Silicon-based (`arm64`) macOS machine, you can use the following command:
53+
54+
```bash
55+
export GOARCH="amd64"
56+
pip install . # or pip install -e .
57+
```
58+
59+
##### Linux
60+
61+
First, install [Zig](https://ziglang.org/download/) on your Linux machine, and set these environment variables prior to installing the package:
62+
63+
Say, on an `amd64` Linux machine:
64+
65+
```bash
66+
export CC="zig cc -target aarch64-linux-gnu"
67+
export CXX="zig c++ -target aarch64-linux-gnu"
68+
export GOARCH="arm64"
69+
pip install . # or pip install -e .
70+
```
71+
72+
will cross-compile a Linux arm64 binary distribution of Hugo that can be used on the targeted arm64 Linux machines. To build a binary distribution for the _target_ `amd64` Linux platform on the _host_ `arm64` Linux machine, set the targets differently:
73+
74+
```bash
75+
export CC="zig cc -target x86_64-linux-gnu"
76+
export CXX="zig c++ -target x86_64-linux-gnu"
77+
export GOARCH="amd64"
78+
pip install . # or pip install -e .
79+
```
80+
81+
This creates dynamic linkage for the built Hugo binary with a system-provided GLIBC. If you wish to statically link the binary with MUSL, change the `CC` and `CXX` environment variables as follows:
82+
83+
```bash
84+
export CC="zig cc -target x86_64-linux-musl"
85+
export CXX="zig c++ -target x86_64-linux-musl"
86+
```
87+
88+
Linkage against MUSL is not tested in CI at this time, but it should work in theory. The official Hugo binaries do not link against MUSL for a variety of reasons including but not limited to the size of the binary and the popularity of the GLIBC C standard library and its conventions.
89+
90+
##### Windows
91+
92+
First, install [Zig](https://ziglang.org/download/) on your Windows machine, and set these environment variables prior to installing the package:
93+
94+
Say, on an `amd64` Windows machine:
95+
96+
```bash
97+
set CC="zig cc -target aarch64-windows-gnu"
98+
set CXX="zig c++ -target aarch64-windows-gnu"
99+
set GOARCH="arm64"
100+
pip install . # or pip install -e .
101+
```
102+
103+
will cross-compile a Windows `arm64` binary distribution of Hugo that can be used on the targeted `arm64` Windows machines (note the use of `set` instead of `export` on Windows), and so on for the `x86` architecture:
104+
105+
```bash
106+
set CC="zig cc -target x86-windows-gnu"
107+
set CXX="zig c++ -target x86-windows-gnu"
108+
set GOARCH="386"
109+
pip install . # or pip install -e .
110+
```
111+
112+
For a list of supported distributions for Go, please run the `go tool dist list` command on your system. For a list of supported targets for Zig, please refer to the [Zig documentation](https://ziglang.org/documentation/) for more information or run the `zig targets` command on your system.
113+
114+
> [!TIP]
115+
> Cross-compilation for a target platform and architecture from a different host platform and architecture is also possible, but it remains largely untested at this time. Currently, the [Zig compiler toolchain](https://ziglang.org/) is known to work for cross-platform, cross-architecture compilation.

0 commit comments

Comments
 (0)