You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
dbd137a Improve build-osx formatting (Giulio Lombardo)
Pull request description:
This `PR` will improve `build-osx.md` formatting by:
1. Updating Markdown syntax to the latest one
2. Adding syntax highlighting to all code blocks
3. Aligning the text up to `80` column guideline (before it was following different guidelines, sometime `80`, sometime `90`, etc.)
4. Small grammar improvements here and there
ACKs for top commit:
fanquake:
ACK dbd137a - Document reads and renders essentially the same as the current `build-osx.md`, with minor formatting / grammatical changes.
Tree-SHA512: 47747991b5fddf0725c82f17f153e83150e51f698787544b4c51b32479989e4b550e2b3aec92979d2b0c76edfdcbbe7c4d9d0115df12e2bfde0cfcb277e9b984
The first time you run bitcoind, it will start downloading the blockchain. This process could take many hours, or even days on slower than average systems.
97
+
The first time you run bitcoind, it will start downloading the blockchain. This process could
98
+
take many hours, or even days on slower than average systems.
92
99
93
100
You can monitor the download process by looking at the debug.log file:
Apple's version of `binutils` (called `cctools`) contains lots of functionality missing in the
127
+
FSF's `binutils`. In addition to extra linker options for frameworks and sysroots, several
128
+
other tools are needed as well such as `install_name_tool`, `lipo`, and `nmedit`. These
129
+
do not build under Linux, so they have been patched to do so. The work here was used as
130
+
a starting point: [mingwandroid/toolchain4](https://github.com/mingwandroid/toolchain4).
128
131
129
-
In order to build a working toolchain, the following source packages are needed
130
-
from Apple: cctools, dyld, and ld64.
132
+
In order to build a working toolchain, the following source packages are needed from
133
+
Apple: `cctools`, `dyld`, and `ld64`.
131
134
132
-
These tools inject timestamps by default, which produce non-deterministic
133
-
binaries. The ZERO_AR_DATE environment variable is used to disable that.
135
+
These tools inject timestamps by default, which produce non-deterministic binaries. The
136
+
`ZERO_AR_DATE` environment variable is used to disable that.
134
137
135
-
This version of cctools has been patched to use the current version of clang's
136
-
headers and its libLTO.so rather than those from llvmgcc, as it was
137
-
originally done in toolchain4.
138
+
This version of `cctools` has been patched to use the current version of `clang`'s headers
139
+
and its `libLTO.so` rather than those from `llvmgcc`, as it was originally done in `toolchain4`.
138
140
139
-
To complicate things further, all builds must target an Apple SDK. These SDKs
140
-
are free to download, but not redistributable.
141
-
To obtain it, register for a developer account, then download the [Xcode 7.3.1 dmg](https://developer.apple.com/devcenter/download.action?path=/Developer_Tools/Xcode_7.3.1/Xcode_7.3.1.dmg).
141
+
To complicate things further, all builds must target an Apple SDK. These SDKs are free to
142
+
download, but not redistributable. To obtain it, register for an Apple Developer Account,
143
+
then download the [Xcode 7.3.1 dmg](https://developer.apple.com/devcenter/download.action?path=/Developer_Tools/Xcode_7.3.1/Xcode_7.3.1.dmg).
142
144
143
-
This file is several gigabytes in size, but only a single directory inside is
144
-
needed:
145
+
This file is several gigabytes in size, but only a single directory inside is needed:
Unfortunately, the usual linux tools (7zip, hpmount, loopback mount) are incapable of opening this file.
150
-
To create a tarball suitable for Gitian input, there are two options:
150
+
Unfortunately, the usual Linux tools (7zip, hpmount, loopback mount) are incapable of
151
+
opening this file. To create a tarball suitable for Gitian input, there are two options:
151
152
152
-
Using macOS, you can mount the dmg, and then create it with:
153
-
```
154
-
$ hdiutil attach Xcode_7.3.1.dmg
155
-
$ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk
153
+
Using macOS, you can mount the DMG, and then create it with:
154
+
```shell
155
+
hdiutil attach Xcode_7.3.1.dmg
156
+
tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk
156
157
```
157
158
158
-
Alternatively, you can use 7zip and SleuthKit to extract the files one by one.
159
-
The script contrib/macdeploy/extract-osx-sdk.sh automates this. First ensure
160
-
the dmg file is in the current directory, and then run the script. You may wish
161
-
to delete the intermediate 5.hfs file and MacOSX10.11.sdk (the directory) when
162
-
you've confirmed the extraction succeeded.
159
+
Alternatively, you can use 7zip and SleuthKit to extract the files one by one. The script
160
+
[`extract-osx-sdk.sh`](./../contrib/macdeploy/extract-osx-sdk.sh) automates this. First
161
+
ensure the DMG file is in the current directory, and then run the script. You may wish to
162
+
delete the `intermediate 5.hfs` file and `MacOSX10.11.sdk` (the directory) when you've
163
+
confirmed the extraction succeeded.
163
164
164
-
```bash
165
+
```shell
165
166
apt-get install p7zip-full sleuthkit
166
167
contrib/macdeploy/extract-osx-sdk.sh
167
168
rm -rf 5.hfs MacOSX10.11.sdk
168
169
```
169
170
170
-
The Gitian descriptors build 2 sets of files: Linux tools, then Apple binaries
171
-
which are created using these tools. The build process has been designed to
172
-
avoid including the SDK's files in Gitian's outputs. All interim tarballs are
173
-
fully deterministic and may be freely redistributed.
171
+
The Gitian descriptors build 2 sets of files: Linux tools, then Apple binaries which are
172
+
created using these tools. The build process has been designed to avoid including the
173
+
SDK's files in Gitian's outputs. All interim tarballs are fully deterministic and may be freely
174
+
redistributed.
174
175
175
-
genisoimage is used to create the initial DMG. It is not deterministic as-is,
176
-
so it has been patched. A system genisoimage will work fine, but it will not
177
-
be deterministic because the file-order will change between invocations.
178
-
The patch can be seen here: [theuni/osx-cross-depends](https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff).
179
-
No effort was made to fix this cleanly, so it likely leaks memory badly. But
180
-
it's only used for a single invocation, so that's no real concern.
176
+
`genisoimage` is used to create the initial DMG. It is not deterministic as-is, so it has been
177
+
patched. A system `genisoimage` will work fine, but it will not be deterministic because
178
+
the file-order will change between invocations. The patch can be seen here: [theuni/osx-cross-depends](https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff).
179
+
No effort was made to fix this cleanly, so it likely leaks memory badly. But it's only used for
180
+
a single invocation, so that's no real concern.
181
181
182
-
genisoimage cannot compress DMGs, so afterwards, the 'dmg' tool from the
183
-
libdmg-hfsplus project is used to compress it. There are several bugs in this
184
-
tool and its maintainer has seemingly abandoned the project. It has been forked
185
-
and is available (with fixes) here: [theuni/libdmg-hfsplus](https://github.com/theuni/libdmg-hfsplus).
182
+
`genisoimage` cannot compress DMGs, so afterwards, the DMG tool from the
183
+
`libdmg-hfsplus` project is used to compress it. There are several bugs in this tool and its
184
+
maintainer has seemingly abandoned the project. It has been forked and is available
The 'dmg' tool has the ability to create DMGs from scratch as well, but this
188
-
functionality is broken. Only the compression feature is currently used.
189
-
Ideally, the creation could be fixed and genisoimage would no longer be necessary.
187
+
The DMG tool has the ability to create DMGs from scratch as well, but this functionality is
188
+
broken. Only the compression feature is currently used. Ideally, the creation could be fixed
189
+
and `genisoimage` would no longer be necessary.
190
190
191
191
Background images and other features can be added to DMG files by inserting a
192
-
.DS_Store before creation. This is generated by the script
193
-
contrib/macdeploy/custom_dsstore.py.
194
-
195
-
As of OS X 10.9 Mavericks, using an Apple-blessed key to sign binaries is a
196
-
requirement in order to satisfy the new Gatekeeper requirements. Because this
197
-
private key cannot be shared, we'll have to be a bit creative in order for the
198
-
build process to remain somewhat deterministic. Here's how it works:
199
-
200
-
- Builders use Gitian to create an unsigned release. This outputs an unsigned
201
-
dmg which users may choose to bless and run. It also outputs an unsigned app
202
-
structure in the form of a tarball, which also contains all of the tools
203
-
that have been previously (deterministically) built in order to create a
204
-
final dmg.
205
-
- The Apple keyholder uses this unsigned app to create a detached signature,
206
-
using the script that is also included there. Detached signatures are available from this [repository](https://github.com/bitcoin-core/bitcoin-detached-sigs).
207
-
- Builders feed the unsigned app + detached signature back into Gitian. It
208
-
uses the pre-built tools to recombine the pieces into a deterministic dmg.
192
+
`.DS_Store` before creation. This is generated by the script
193
+
`contrib/macdeploy/custom_dsstore.py`.
194
+
195
+
As of OS X 10.9 Mavericks, using an Apple-blessed key to sign binaries is a requirement in
196
+
order to satisfy the new Gatekeeper requirements. Because this private key cannot be
197
+
shared, we'll have to be a bit creative in order for the build process to remain somewhat
198
+
deterministic. Here's how it works:
199
+
200
+
- Builders use Gitian to create an unsigned release. This outputs an unsigned DMG which
201
+
users may choose to bless and run. It also outputs an unsigned app structure in the form
202
+
of a tarball, which also contains all of the tools that have been previously (deterministically)
203
+
built in order to create a final DMG.
204
+
- The Apple keyholder uses this unsigned app to create a detached signature, using the
205
+
script that is also included there. Detached signatures are available from this [repository](https://github.com/bitcoin-core/bitcoin-detached-sigs).
206
+
- Builders feed the unsigned app + detached signature back into Gitian. It uses the
207
+
pre-built tools to recombine the pieces into a deterministic DMG.
0 commit comments