Skip to content

Commit f615f51

Browse files
KenoKeno
authored
Merge pull request #97 from JuliaPackaging/kf/morestuff
Fix one more issue and update README
2 parents 7e18305 + 408fe6a commit f615f51

File tree

2 files changed

+143
-123
lines changed

2 files changed

+143
-123
lines changed

‎README.md‎

Lines changed: 40 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,45 @@
1-
# PRE-ALPHA SOFTWARE
1+
# BETA SOFTWARE
22

3-
The code monkeys are still hard at work tinkering to develop the best possible binary building solution for [Julia](https://julialang.org). Please **do not use this software** for any real work until this notice is removed. This software is provided AS-IS with no warranty, implied or otherwise, and is not even guaranteed to be fit for a particular purpose.
3+
Though most of the design work has been completed, the code monkeys are still hard at work tinkering to develop the best possible binary building solution for [Julia](https://julialang.org). Feel free to use this software, but please note
4+
that there may be bugs and issues still being worked out. This software is provided AS-IS with no warranty, implied or otherwise, and is not even guaranteed to be fit for a particular purpose.
5+
6+
The primary target platform of this package is Linux.
7+
Windows is currently not supported. Please note that although preliminary OS X
8+
support exists, it is experimental and recommended only to those wanting to help
9+
out with porting this package to new platforms.
410

511
# BinaryBuilder
612

713
[![Build Status](https://travis-ci.org/JuliaPackaging/BinaryBuilder.jl.svg?branch=master)](https://travis-ci.org/JuliaPackaging/BinaryBuilder.jl) [![codecov.io](http://codecov.io/github/JuliaPackaging/BinaryBuilder.jl/coverage.svg?branch=master)](http://codecov.io/github/JuliaPackaging/BinaryBuilder.jl?branch=master)
814

915
"Yea, though I walk through the valley of the shadow of death, I will fear no evil"
1016

17+
# Usage
18+
19+
This package will help you create a distribution of binary dependencies for your
20+
julia package. Generally this is accomplished using a dependency-specific,
21+
`build_tarballs.jl` file ([example](https://github.com/Keno/ReadStatBuilder/blob/master/build_tarballs.jl))
22+
that builds the binary for all platforms. These tarballs are then suitable for
23+
installation using `BinaryProvider.jl`. Currently we recommend creating a
24+
separate GitHub repository for the `build_tarballs.jl` script and using that
25+
repository's `GitHub Releases` page to host the binaries.
26+
27+
The contents of the `build_tarballs.jl` file is relatively straightforward,
28+
but getting it right can be a little tricky. To ease the burden of creating
29+
said file, you may use the BinaryBuilder wizard:
30+
31+
```
32+
using BinaryBuilder
33+
BinaryBuilder.run_wizard()
34+
```
35+
36+
The wizard will take you through creating the `build_tarballs.jl` file and help
37+
you deploy the result to GitHub with Travis and GitHub releases set up properly.
38+
Once you complete the wizard and your repository is created on GitHub, create
39+
a new release on the `GitHub Releases` page and Travis will automatically add
40+
binaries for all platforms, as well as a build.jl file that you can use in your
41+
julia package to import the binaries you have just built.
42+
1143
# Philosophy
1244

1345
Building binary packages is a pain. `BinaryBuilder` is here to make your life easier. `BinaryBuilder` follows a philosophy that is similar to that of building [Julia](https://julialang.org) itself; when you want something done right, you do it yourself.
@@ -18,28 +50,14 @@ We do not use system package managers.
1850

1951
We do not provide multiple ways to install a dependency. It's download and unpack tarball, or nothing.
2052

21-
# Implementation
22-
23-
`BinaryBuilder.jl` utilizes a cross-compilation environment built into a [Docker](https://www.docker.com) image to compile binary objects for multiple operating systems and architectures. The Dockerfiles for creating this cross-compilation environment are hosted in [the `staticfloat/julia-docker` repository](https://github.com/staticfloat/julia-docker/blob/master/crossbuild/crossbuild-x64.harbor). The docker image contains cross-compilation toolchains stored in `/opt/<target triplet>`, see [`target_envs()`](https://github.com/JuliaPackaging/BinaryBuilder.jl/blob/76a3073753bd017aaf522ed068ea29418f1059c0/src/DockerRunner.jl#L108-L133) for an example of what kinds of environment variables are defined in order to run the proper tools for a particular cross-compilation task.
24-
25-
A build is represented by a [`Dependency` object](https://github.com/JuliaPackaging/BinaryBuilder.jl/blob/76a3073753bd017aaf522ed068ea29418f1059c0/src/Dependency.jl#L17-L36), which is used to bundle together all the build steps required to actually build an object, perform the build, write out logs for each step, and finally package it all up as a nice big tarball. At the end of a `build()`, a series of audit steps are run, checking for common problems such as missing libraries. These checks typically do not stop a build, but you should pay attention to them, as they do their best to be helpful. Occasionally, an error can be automatically fixed. If you set the `autofix` parameter to `build()` to be `true`, this will be attempted.
26-
27-
# Usage example
53+
All packages are cross compiled. If a package does not support cross compilation, fix the package.
2854

29-
Usage is as simple as defining a `Dependency`, `build()`'ing it, then packaging it up. Example:
30-
31-
```julia
32-
prefix = Prefix("/source_code")
33-
cd("/source_code") do
34-
libfoo = LibraryProduct(prefix, "libfoo")
35-
steps = [`make clean`, `make install`]
36-
dep = Dependency("foo", [libfoo], steps, :linux64, prefix)
37-
build(dep)
38-
end
39-
tarball_path = package(prefix, "/build_out/libfoo", platform=platform)
40-
```
55+
# Implementation
4156

42-
For a full example, see [`build_libfoo_tarballs.jl` in the test directory](test/build_libfoo_tarballs.jl). For a more in-depth example, see [the NettleBuilder repository](https://github.com/staticfloat/NettleBuilder).
57+
`BinaryBuilder.jl` utilizes a cross-compilation environment exposed as a Linux container.
58+
On Linux this makes use of a light-weight custom container engine, on OS X (and
59+
Windows in the future), we use qemu and hardware accelerated virtualization to
60+
provide the environment. The environment contains cross-compilation toolchains stored in `/opt/<target triplet>`. See [`target_envs()`](https://github.com/JuliaPackaging/BinaryBuilder.jl/blob/76a3073753bd017aaf522ed068ea29418f1059c0/src/DockerRunner.jl#L108-L133) for an example of what kinds of environment variables are defined in order to run the proper tools for a particular cross-compilation task.
4361

4462
# Known issues
4563

‎src/wizard/interactive_build.jl‎

Lines changed: 103 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -297,117 +297,120 @@ function step5_internal(state::WizardState, platform::Platform, message)
297297

298298
build_path = tempname()
299299
mkpath(build_path)
300-
local ok = true
301-
cd(build_path) do
302-
prefix, ur = setup_workspace(
303-
build_path,
304-
state.source_files,
305-
state.source_hashes,
306-
state.dependencies,
307-
platform,
308-
Dict("HISTFILE"=>"/workspace/.bash_history");
309-
verbose=true,
310-
tee_stream=state.outs
311-
)
300+
local ok = false
301+
while !ok
302+
cd(build_path) do
303+
prefix, ur = setup_workspace(
304+
build_path,
305+
state.source_files,
306+
state.source_hashes,
307+
state.dependencies,
308+
platform,
309+
Dict("HISTFILE"=>"/workspace/.bash_history");
310+
verbose=true,
311+
tee_stream=state.outs
312+
)
312313

313-
run(ur,
314-
`/bin/bash -c $(state.history)`,
315-
joinpath(build_path,"out.log");
316-
verbose=true,
317-
tee_stream=state.outs
318-
)
314+
run(ur,
315+
`/bin/bash -c $(state.history)`,
316+
joinpath(build_path,"out.log");
317+
verbose=true,
318+
tee_stream=state.outs
319+
)
319320

320-
while true
321-
msg = "\n\t\t\tBuild complete. Analyzing...\n\n"
322-
print_with_color(:bold, state.outs, msg)
323-
324-
audit(prefix; io=state.outs,
325-
platform=platform, verbose=true, autofix=true)
326-
327-
ok = isempty(match_files(state, prefix, platform, state.files))
328-
if !ok
329-
println(state.outs)
330-
print_with_color(:red, state.outs, "ERROR: ")
331-
msg = "Some build products could not be found (see above)."
332-
println(state.outs, msg)
333-
println(state.outs)
334-
335-
# N.B.: This is a Star Trek reference (TNG Season 1, Episode 25,
336-
# 25:00).
337-
choice = request(terminal,
338-
"Please specify how you would like to proceed, sir.",
339-
RadioMenu([
340-
"Drop into build environment",
341-
"Open a clean session for this platform",
342-
"Disable this platform",
343-
"Edit build script",
344-
])
345-
)
346-
347-
if choice == 1
348-
if interactive_build(state, prefix, ur, build_path;
349-
hist_modify = function(olds, s)
350-
"""
351-
$olds
352-
if [ \$target = "$(triplet(platform))" ]; then
353-
$s
354-
fi
355-
"""
356-
end)
357-
# We'll go around again after this
358-
break
359-
else
360-
# Go back to analysis of the newly environment
361-
continue
362-
end
363-
elseif choice == 2
364-
rmdir(build_path; recursive = true)
365-
mkpath(build_path)
366-
prefix, ur = setup_workspace(
367-
build_path,
368-
state.source_files,
369-
state.source_hashes,
370-
state.dependencies,
371-
platform,
372-
Dict("HISTFILE"=>"/workspace/.bash_history");
373-
verbose=true,
374-
tee_stream=state.outs
321+
while true
322+
msg = "\n\t\t\tBuild complete. Analyzing...\n\n"
323+
print_with_color(:bold, state.outs, msg)
324+
325+
audit(prefix; io=state.outs,
326+
platform=platform, verbose=true, autofix=true)
327+
328+
ok = isempty(match_files(state, prefix, platform, state.files))
329+
if !ok
330+
println(state.outs)
331+
print_with_color(:red, state.outs, "ERROR: ")
332+
msg = "Some build products could not be found (see above)."
333+
println(state.outs, msg)
334+
println(state.outs)
335+
336+
# N.B.: This is a Star Trek reference (TNG Season 1, Episode 25,
337+
# 25:00).
338+
choice = request(terminal,
339+
"Please specify how you would like to proceed, sir.",
340+
RadioMenu([
341+
"Drop into build environment",
342+
"Open a clean session for this platform",
343+
"Disable this platform",
344+
"Edit build script",
345+
])
375346
)
376-
if interactive_build(state, prefix, ur, build_path;
377-
hist_modify = function(olds, s)
378-
"""
379-
if [ \$target != "$(triplet(platform))" ]; then
380-
$olds
347+
348+
if choice == 1
349+
if interactive_build(state, prefix, ur, build_path;
350+
hist_modify = function(olds, s)
351+
"""
352+
$olds
353+
if [ \$target = "$(triplet(platform))" ]; then
354+
$s
355+
fi
356+
"""
357+
end)
358+
# We'll go around again after this
359+
break
381360
else
382-
$s
383-
fi
384-
"""
385-
end)
386-
# We'll go around again after this
361+
# Go back to analysis of the newly environment
362+
continue
363+
end
364+
elseif choice == 2
365+
rmdir(build_path; recursive = true)
366+
mkpath(build_path)
367+
prefix, ur = setup_workspace(
368+
build_path,
369+
state.source_files,
370+
state.source_hashes,
371+
state.dependencies,
372+
platform,
373+
Dict("HISTFILE"=>"/workspace/.bash_history");
374+
verbose=true,
375+
tee_stream=state.outs
376+
)
377+
if interactive_build(state, prefix, ur, build_path;
378+
hist_modify = function(olds, s)
379+
"""
380+
if [ \$target != "$(triplet(platform))" ]; then
381+
$olds
382+
else
383+
$s
384+
fi
385+
"""
386+
end)
387+
# We'll go around again after this
388+
break
389+
else
390+
# Go back to analysis of the newly environment
391+
continue
392+
end
393+
elseif choice == 3
394+
filter!(p->p != platform, state.platforms)
395+
ok = true
396+
break
397+
elseif choice == 4
398+
change_script!(state, edit_script(state, state.history))
387399
break
388-
else
389-
# Go back to analysis of the newly environment
390-
continue
400+
# Well go around again after this
391401
end
392-
elseif choice == 3
393-
filter!(p->p != platform, state.platforms)
402+
else
394403
ok = true
404+
push!(state.validated_platforms, platform)
405+
println(state.outs, "")
406+
msg = "You have successfully built for $platform. Congratulations!"
407+
println(state.outs, msg)
395408
break
396-
elseif choice == 4
397-
change_script!(state, edit_script(state, state.history))
398-
break
399-
# Well go around again after this
400409
end
401-
else
402-
push!(state.validated_platforms, platform)
403-
println(state.outs, "")
404-
msg = "You have successfully built for $platform. Congratulations!"
405-
println(state.outs, msg)
406-
break
407410
end
408-
end
409411

410-
println(state.outs)
412+
println(state.outs)
413+
end
411414
end
412415
return ok
413416
end
@@ -437,7 +440,6 @@ function step5a(state::WizardState)
437440
if step5_internal(state, platform, msg)
438441
push!(state.visited_platforms, platform)
439442
state.step = :step5b
440-
# Otherwise go around again
441443
end
442444
end
443445

0 commit comments

Comments
 (0)