The official documentation sorely needs an explanation of the rust runtime and what it is exactly, and I want this guide to provide that information.
I'm unsure of whether I've been too light on some topics while too heavy on others. I also feel like a few things are still missing. As always, feedback is appreciated, especially about things you'd like to see written about!
This reorganizes the documentation index to be more focused on the in-tree docs, and to clean up the style, and it also adds @steveklabnik's pointer guide.
Ensure configure creates doc/guides directory
Fix configure makefile and tests
Remove old guides dir and configure option, convert testing to guide
Remove ignored files
Fix submodule issue
prepend dir in makefile so that bor knows how to build the docs
S to uppercase
This pull request extracts all scheduling functionality from libstd, moving it into its own separate crates. The new libnative and libgreen will be the new way in which 1:1 and M:N scheduling is implemented. The standard library still requires an interface to the runtime, however, (think of things like `std::comm` and `io::println`). The interface is now defined by the `Runtime` trait inside of `std::rt`.
The booting process is now that libgreen defines the start lang-item and that's it. I want to extend this soon to have libnative also have a "start lang item" but also allow libgreen and libnative to be linked together in the same process. For now though, only libgreen can be used to start a program (unless you define the start lang item yourself). Again though, I want to change this soon, I just figured that this pull request is large enough as-is.
This certainly wasn't a smooth transition, certain functionality has no equivalent in this new separation, and some functionality is now better enabled through this new system. I did my best to separate all of the commits by topic and keep things fairly bite-sized, although are indeed larger than others.
As a note, this is currently rebased on top of my `std::comm` rewrite (or at least an old copy of it), but none of those commits need reviewing (that will all happen in another pull request).
It only really makes sense to run tests for the build target anyway because it's
not guaranteed that you can execute other targets.
This is blocking the next snapshot
Right now multiple targets/hosts is broken because the libdir passed for all of
the LLVM libraries is for the wrong architecture. By using the right arch
(target, not host), everything is linked and assembled just fine.
In order to keep up to date with changes to the libraries that `llvm-config`
spits out, the dependencies to the LLVM are a dynamically generated rust file.
This file is now automatically updated whenever LLVM is updated to get kept
up-to-date.
At the same time, this cleans out some old cruft which isn't necessary in the
makefiles in terms of dependencies.
Closes#10745Closes#10744
CFG_BUILD_DIR, CFG_LLVM_SRC_DIR and CFG_SRC_DIR all have trailing
slashes, by definition, so this is correct.
(This is purely cosmetic; the doubled slash is ignored by all the tools we're using.)
This infrastructure is meant to support runnings tests that involve various
interesting interdependencies about the types of crates being linked or possibly
interacting with C libraries. The goal of these make tests is to not restrict
them to a particular test runner, but allow each test to run its own tests.
To this end, there is a new src/test/run-make directory which has sub-folders of
tests. Each test requires a `Makefile`, and running the tests constitues simply
running `make` inside the directory. The new target is `check-stageN-rmake`.
These tests will have the destination directory (as TMPDIR) and the local rust
compiler (as RUSTC) passed along to them. There is also some helpful
cross-platform utilities included in src/test/run-make/tools.mk to aid with
compiling C programs and running them.
The impetus for adding this new test suite is to allow various interesting forms
of testing rust linkage. All of the tests initially added are various flavors of
compiling Rust and C with one another as well as just making sure that rust
linkage works in general.
Closes#10434
This commit implements the support necessary for generating both intermediate
and result static rust libraries. This is an implementation of my thoughts in
https://mail.mozilla.org/pipermail/rust-dev/2013-November/006686.html.
When compiling a library, we still retain the "lib" option, although now there
are "rlib", "staticlib", and "dylib" as options for crate_type (and these are
stackable). The idea of "lib" is to generate the "compiler default" instead of
having too choose (although all are interchangeable). For now I have left the
"complier default" to be a dynamic library for size reasons.
Of the rust libraries, lib{std,extra,rustuv} will bootstrap with an
rlib/dylib pair, but lib{rustc,syntax,rustdoc,rustpkg} will only be built as a
dynamic object. I chose this for size reasons, but also because you're probably
not going to be embedding the rustc compiler anywhere any time soon.
Other than the options outlined above, there are a few defaults/preferences that
are now opinionated in the compiler:
* If both a .dylib and .rlib are found for a rust library, the compiler will
prefer the .rlib variant. This is overridable via the -Z prefer-dynamic option
* If generating a "lib", the compiler will generate a dynamic library. This is
overridable by explicitly saying what flavor you'd like (rlib, staticlib,
dylib).
* If no options are passed to the command line, and no crate_type is found in
the destination crate, then an executable is generated
With this change, you can successfully build a rust program with 0 dynamic
dependencies on rust libraries. There is still a dynamic dependency on
librustrt, but I plan on removing that in a subsequent commit.
This change includes no tests just yet. Our current testing
infrastructure/harnesses aren't very amenable to doing flavorful things with
linking, so I'm planning on adding a new mode of testing which I believe belongs
as a separate commit.
Closes#552
This commit moves all thread-blocking I/O functions from the std::os module.
Their replacements can be found in either std::rt::io::file or in a hidden
"old_os" module inside of native::file. I didn't want to outright delete these
functions because they have a lot of special casing learned over time for each
OS/platform, and I imagine that these will someday get integrated into a
blocking implementation of IoFactory. For now, they're moved to a private module
to prevent bitrot and still have tests to ensure that they work.
I've also expanded the extensions to a few more methods defined on Path, most of
which were previously defined in std::os but now have non-thread-blocking
implementations as part of using the current IoFactory.
The api of io::file is in flux, but I plan on changing it in the next commit as
well.
Closes#10057
Similarly to the previous commit, libuv is only used by this library, so there's
no need for it to be linked into librustrt and available to all crates by
default.
Allows an enum with a discriminant to use any of the primitive integer types to store it. By default the smallest usable type is chosen, but this can be overridden with an attribute: `#[repr(int)]` etc., or `#[repr(C)]` to match the target's C ABI for the equivalent C enum.
Also adds a lint pass for using non-FFI safe enums in extern declarations, checks that specified discriminants can be stored in the specified type if any, and fixes assorted code that was assuming int.
The actual fix would be to make rustpkg use `rustc::monitor` so it picks
up anything special that rustc needs, but for now let's keep the tests
from breaking.
There are a few reasons that this is a desirable move to take:
1. Proof of concept that a third party event loop is possible
2. Clear separation of responsibility between rt::io and the uv-backend
3. Enforce in the future that the event loop is "pluggable" and replacable
Here's a quick summary of the points of this pull request which make this
possible:
* Two new lang items were introduced: event_loop, and event_loop_factory.
The idea of a "factory" is to define a function which can be called with no
arguments and will return the new event loop as a trait object. This factory
is emitted to the crate map when building an executable. The factory doesn't
have to exist, and when it doesn't then an empty slot is in the crate map and
a basic event loop with no I/O support is provided to the runtime.
* When building an executable, then the rustuv crate will be linked by default
(providing a default implementation of the event loop) via a similar method to
injecting a dependency on libstd. This is currently the only location where
the rustuv crate is ever linked.
* There is a new #[no_uv] attribute (implied by #[no_std]) which denies
implicitly linking to rustuv by default
Closes#5019
api::install_pkg now accepts an argument that's a list of
(kind, path) dependency pairs. This allows custom package scripts to
declare C dependencies, as is demonstrated in
rustpkg::tests::test_c_dependency_ok.
Closes#6403
As discovered in #9925, it turns out that we weren't using jemalloc on most
platforms. Additionally, on some platforms we were using it incorrectly and
mismatching the libc version of malloc with the jemalloc version of malloc.
Additionally, it's not clear that using jemalloc is indeed a large performance
win in particular situtations. This could be due to building jemalloc
incorrectly, or possibly due to using jemalloc incorrectly, but it is unclear at
this time.
Until jemalloc can be confirmed to integrate correctly on all platforms and has
verifiable large performance wins on platforms as well, it shouldn't be part of
the default build process. It should still be available for use via the
LD_PRELOAD trick on various architectures, but using it as the default allocator
for everything would require guaranteeing that it works in all situtations,
which it currently doesn't.
Closes#9925
Sadly, there's a lack of resources for maintaining the `rust` tool,
and we decided in the 2013-10-08 Rust team meeting that it's better
to remove it altogether than to leave it in a broken state.
This deletion is without prejudice. If a person or people appear who
would like to maintain the tool, we will probably be happy to
resurrect it!
Closes#9775
Removes old rustdoc, moves rustdoc_ng into its place instead (plus drops the _ng
suffix). Also shreds all reference to rustdoc_ng from the Makefile rules.
Many people will be very confused that their debug! statements aren't working
when they first use rust only to learn that they should have been building with
`--cfg debug` the entire time. This inverts the meaning of the flag to instead
of enabling debug statements, now it disables debug statements.
This way the default behavior is a bit more reasonable, and requires less
end-user configuration. Furthermore, this turns on debug by default when
building the rustc compiler.
Now rustdoc_ng will be built as both a binary and a library (using the same
rules as all the other binaries that rust has). Furthermore, this will also
start building rustdoc_ng unit tests (and running them).
`stdtest` and `extratest` expects to be able to write to `tmp` directory under the current working directory, so the first commit creates `tmp` directory and changes the directory before running tests.
The second commit adds `--bench` argument to test runs and copies metrics from the remote device.
r? @graydon Also, notably, make rustpkgtest depend on the rustpkg executable (otherwise, tests that shell out to rustpgk might run when rustpkg doesn't exist).
Get rid of special cases for names beginning with "rust-" or
containing hyphens, and just store a Path in a package ID. The Rust-identifier
for the crate is none of rustpkg's business.
This commit allows you to write:
extern mod x = "a/b/c";
which means rustc will search in the RUST_PATH for a package with
ID a/b/c, and bind it to the name `x` if it's found.
Incidentally, move get_relative_to from back::rpath into std::path
r? anyone
Fix#8057
This commit fixes some oversights in the Makefile where rustc could be
invoked without some of its dependencies yet in place. (I encountered
the problem in practice; its not just theoretical.)
As written in Makefile.in, $(STAGE$(1)_T_$(2)_H_$(3)) is the way one
writes an invocation of rustc where $(1) is the stage number $(2) is
the target triple $(3) is the host triple. (Other uses of the macro
may plug in actual values or different parameters in for those three
formal parameters.)
When you have invocations of $(STAGE...), you need to make sure that
its dependences are satisfied; otherwise, if someone is using `make
-jN` for certain (large-ish) `N`, one can encounter situations where
GNU make attempts to invoke `rustc` before it has actually copied some
of its libraries into place, such as libmorestack.a, which causes a
link failure when the rustc invocation attempts to link in those
libraries.
In this case, the main prerequisite to add is TSREQ$(1)_T_$(2)_H_$(3),
which is described in Makefile.in as "Prerequisites for using the
stageN compiler to build target artifacts"
----
In addition to adding the extra dependences on TSREQ..., I also
replaced occurrences of the pattern:
TSREQ$(1)_T_$(2)_H_$(3)
$$(TLIB$(1)_T_$(2)_H_$(3))/$(CFG_STDLIB_$(2))
$$(TLIB$(1)_T_$(2)_H_$(3))/$(CFG_EXTRALIB_$(2))
with:
SREQ$(1)_T_$(2)_H_$(3)
which is equivalent to the above, as defined in Makefile.in
----
Finally, for the cases where TSREQ was missing in tests.mk, I went
ahead and put in a dependence on SREQ rather than just TSREQ, since it
was not clear to me how one could expect to compile those cases
without stdlib and extralib.
(It could well be that I should have gone ahead and done the same in
other cases where I saw TSREQ was missing, and put SREQ in those
cases as well. But this seemed like a good measure for now, without
needing to tax my understanding of the overall makefile
infrastructure much further.)
Remove directive, if present, from CFG_RUSTC_FLAGS.
Fix#7898.
(One alternative tack is to build up distinct CFG_TEST_RUSTC_FLAGS
alongside CFG_RUSTC_FLAGS; but currently debug is the only --cfg flag
ever added to CFG_RUSTC_FLAGS; the other contents of CFG_RUSTC_FLAGS
are a mix of -Z flags and a few other switches like O, which seem to
make sense to propogate to the tests.)
This commit fixes some oversights in the Makefile where rustc could be
invoked without some of its dependencies yet in place. (I encountered
the problem in practice; its not just theoretical.)
As written in Makefile.in, $(STAGE$(1)_T_$(2)_H_$(3)) is the way one
writes an invocation of rustc where $(1) is the stage number $(2) is
the target triple $(3) is the host triple. (Other uses of the macro
may plug in actual values or different parameters in for those three
formal parameters.)
When you have invocations of $(STAGE...), you need to make sure that
its dependences are satisfied; otherwise, if someone is using `make
-jN` for certain (large-ish) `N`, one can encounter situations where
GNU make attempts to invoke `rustc` before it has actually copied some
of its libraries into place, such as libmorestack.a, which causes a
link failure when the rustc invocation attempts to link in those
libraries.
In this case, the main prerequisite to add is TSREQ$(1)_T_$(2)_H_$(3),
which is described in Makefile.in as "Prerequisites for using the
stageN compiler to build target artifacts"
----
In addition to adding the extra dependences on TSREQ..., I also
replaced occurrences of the pattern:
TSREQ$(1)_T_$(2)_H_$(3)
$$(TLIB$(1)_T_$(2)_H_$(3))/$(CFG_STDLIB_$(2))
$$(TLIB$(1)_T_$(2)_H_$(3))/$(CFG_EXTRALIB_$(2))
with:
SREQ$(1)_T_$(2)_H_$(3)
which is equivalent to the above, as defined in Makefile.in
----
Finally, for the cases where TSREQ was missing in tests.mk, I went
ahead and put in a dependence on SREQ rather than just TSREQ, since it
was not clear to me how one could expect to compile those cases
without stdlib and extralib.
(It could well be that I should have gone ahead and done the same in
other cases where I saw TSREQ was missing, and put SREQ in those
cases as well. But this seemed like a good measure for now, without
needing to tax my understanding of the overall makefile
infrastructure much further.)
Most of the relevant information can be found in the commit messages.
r? @brson - I just wanted to make sure the make changes aren't completely bogus
This would close#2400, #6517, and #6489 (although a run through incoming-full on linux would have to confirm the latter two)
This way a cross-compiled rustc's answer to host_triple() is correct. The return
value of host_triple() reflects the actual host triple that the compiler was
build for, not the triple the compiler is being built on
* They didn't work before, because the location of the tests caused the
'sysroot' option to crate lookup to be wrong for finding the correct stage's
core/std libraries. This moves the compiled tests from the $host/test
directory into a $host/$stage/test directory. This means that the sysroot will
be correct and the core/std libraries can actually be found
* The LLVM bindings apparently aren't threadsafe, so we can't run multiple tests
in parallel.
Support #5297
install.mk : install-runtime-target added for conveneice
automatically push runtime library to android device
test.mk : expanded to support android test automation with adb
compiletest : expanded to support android test automation with adb
Add an optional --logfile argument to std::test::test_main and to
compiletest.
Use this features and the new 'check-summary.py' script to
summarise all the tests performed by the 'check' target. This is
a short term fix for #2075.
`make check` executes `tidy` after compile. It reminds me that I've left
long lines or trailing whitespaces only after compilation finshed. That
is too late since I have to recompile only because fixing the trivial
formatting issues.
Run tidy first to avoid potentially unnecessary re-compilation.
Each stage is organized more according to Unix standards and to
accommodate multiple target architectures.
stageN/
bin - rustc lives here
lib - libraries that rustc needs
lib/rustc/$(target_triple/ - target libraries
This was having the effect of scrubbing failure error codes. The only affect
of removing this should be that the .out file isn't generated, so subsequent
make invocations will re-run the tests (which is how our other tests work
anyway).
Add a new src/test/pretty directory to hold just source files for testing the
pretty-printer.
Add a new pp-exact directive. When this directive is followed by a file name
it specifies a file containing the output that the pretty-printer should
generate. When pp-exact is not followed by a filename it says that the file
should pretty-print as written.
This will reduce the valgrind deluge when a test fails. The tests themselves
are still run under valgrind. Leave a CTEST_VALGRIND environment variable for
running with the old behavior.
This replaces the make-based test runner with a set of Rust-based test
runners. I believe that all existing functionality has been
preserved. The primary objective is to dogfood the Rust test
framework.
A few main things happen here:
1) The run-pass/lib-* tests are all moved into src/test/stdtest. This
is a standalone test crate intended for all standard library tests. It
compiles to build/test/stdtest.stageN.
2) rustc now compiles into yet another build artifact, this one a test
runner that runs any tests contained directly in the rustc crate. This
allows much more fine-grained unit testing of the compiler. It
compiles to build/test/rustctest.stageN.
3) There is a new custom test runner crate at src/test/compiletest
that reproduces all the functionality for running the compile-fail,
run-fail, run-pass and bench tests while integrating with Rust's test
framework. It compiles to build/test/compiletest.stageN.
4) The build rules have been completely changed to use the new test
runners, while also being less redundant, following the example of the
recent stageN.mk rewrite.
It adds two new features to the cfail/rfail/rpass/bench tests:
1) Tests can specify multiple 'error-pattern' directives which must be
satisfied in order.
2) Tests can specify a 'compile-flags' directive which will make the
test runner provide additional command line arguments to rustc.
There are some downsides, the primary being that Rust has to be
functioning pretty well just to run _any_ tests, which I imagine will
be the source of some frustration when the entire test suite
breaks. Will also cause some headaches during porting.
Not having individual make rules, each rpass, etc test no longer
remembers between runs whether it completed successfully. As a result,
it's not possible to incrementally fix multiple tests by just running
'make check', fixing a test, and repeating without re-running all the
tests contained in the test runner. Instead you can filter just the
tests you want to run by using the TESTNAME environment variable.
This also dispenses with the ability to run stage0 tests, but they
tended to be broken more often than not anyway.
This will link to std and compile with the --test flag. Eventually the
run-pass/lib* tests will move here.
We could also put the std tests directly into the library and compile both a
library version and a test version, but I think this way will make for faster
builds.
Issue #428
The tinderbox snapshotting scripts seem to be looking for a stage2-check
target when they should be using check-stage2. Since Graydon is out of the
office, I'm making this change to see if the snapshot will go through.
bors