In the process, `Splits` got changed to be more like `CharSplits` in `str` to present the DEI interface.
Note that `treemap` still has a `rev_iter` function because it seems like it would be a significant interface change to expose a DEI - the iterator would have to gain an extra pointer, the completion checks would be more complicated, and it isn't easy to check that such an implementation is correct due to the use of unsafety to subvert the aliasing properties of `&mut`.
This fixes#9391.
Two selector fixes for rustdoc:
- links colored in blue (#13807) was also affecting headers, which are anchored to their respective ids
- the header unstyling from #13776 was being applied to all headers also
Additionally, remove a stray title in the documentation. This makes the crate title of prelude appear as header instead of an inline paragraph of text (all others work normally and do not have that header tag).
The design is unchanged from my previous template (e.g. [here](http://adrientetar.legtux.org/cached/rust-docs/struct.CChars.htm)), however it is now properly applied.
The last fix remaining is to enable webfonts service from `static.rust-lang.org`, this is #13593.
r? @alexcrichton, @brson
Hi rust enthusiasts,
With this patch I propose to add a "streaming" API to the existing json parser in libserialize.
By "streaming" I mean a parser that let you act on JsonEvents that are generated as while parsing happens, as opposed to parsing the entire source, generating a big data structure and working with this data structure. I think both approaches have their pros and cons so this pull request adds the streaming API, preserving the existing one.
The streaming API is simple: It consist into an Iterator<JsonEvent> that consumes an Iterator<char>. JsonEvent is an enum with values such as NumberValue(f64), BeginList, EndList, BeginObject, etc.
The user would ideally use the API as follows:
```
for evt in StreamingParser::new(src) {
match evt {
BeginList => {
// ...
}
// ...
}
}
```
The iterator provides a stack() method returning a slice of StackNodes which represent "where we currently are" in the logical structure of the json stream (for instance at "foo.bar[3].x" you get [ Key("foo"), Key("bar"), Index(3), Key("x") ].)
I wrote "ideally" above because the current way rust expands for loops, you can't call the stack() method because the iterator is already borrowed. So for know you need to manually advance the iterator in the loop. I hope this is something we can cope with, until for loops are better integrated with the compiler.
Streaming parsers are useful when you want to read from a json stream, generate a custom data structure and you know how the json is going to be structured. For example, imagine you have to parse a 3D mesh file represented in the json format. In this case you probably expect to have large arrays of vertices and using the generic parser will be very inefficient because it will create a big list of all these vertices, which you will copy into a contiguous array afterwards (so you end up doing a lot of small allocations, parsing the json once and parsing the data structure afterwards). With a streaming parser, you can add the vertices to a contiguous array as they come in without paying the cost of creating the intermediate Json data structure. You have much fewer allocations since you write directly in the final data structure and you can be smart in how you will pre-allocate it.
I added added this directly into serialize::json rather than in its own library because it turns out I can reuse most of the existing code whereas maintaining a separate library (which I did originally) forces me to duplicate this code.
I wrote this trying to minimize the size of the patch so there may be places where the code could be nicer at the expenses of more changes (let me know what you prefer).
This is my first (potential) contribution to rust, so please let me know if I am doing something wrong (maybe I should have first introduced this proposition in the mailing list, or opened a github issue, etc.?). I work a few meters away from @pknfelix so I am not too hard to find :)
When a syntax extension is loaded by the compiler, the dylib that is opened may
have other dylibs that it depends on. The dynamic linker must be able to find
these libraries on the system or else the library will fail to load.
Currently, unix gets by with the use of rpaths. This relies on the dylib not
moving around too drastically relative to its dependencies. For windows,
however, this is no rpath available, and in theory unix should work without
rpaths as well.
This modifies the compiler to add all -L search directories to the dynamic
linker's set of load paths. This is currently managed through environment
variables for each platform.
Closes#13848
When a syntax extension is loaded by the compiler, the dylib that is opened may
have other dylibs that it depends on. The dynamic linker must be able to find
these libraries on the system or else the library will fail to load.
Currently, unix gets by with the use of rpaths. This relies on the dylib not
moving around too drastically relative to its dependencies. For windows,
however, this is no rpath available, and in theory unix should work without
rpaths as well.
This modifies the compiler to add all -L search directories to the dynamic
linker's set of load paths. This is currently managed through environment
variables for each platform.
Closes#13848
The compiler has previously been producing binaries on the order of 1.8MB for
hello world programs "fn main() {}". This is largely a result of the compilation
model used by compiling entire libraries into a single object file and because
static linking is favored by default.
When linking, linkers will pull in the entire contents of an object file if any
symbol from the object file is used. This means that if any symbol from a rust
library is used, the entire library is pulled in unconditionally, regardless of
whether the library is used or not.
Traditional C/C++ projects do not normally encounter these large executable
problems because their archives (rust's rlibs) are composed of many objects.
Because of this, linkers can eliminate entire objects from being in the final
executable. With rustc, however, the linker does not have the opportunity to
leave out entire object files.
In order to get similar benefits from dead code stripping at link time, this
commit enables the -ffunction-sections and -fdata-sections flags in LLVM, as
well as passing --gc-sections to the linker *by default*. This means that each
function and each global will be placed into its own section, allowing the
linker to GC all unused functions and data symbols.
By enabling these flags, rust is able to generate much smaller binaries default.
On linux, a hello world binary went from 1.8MB to 597K (a 67% reduction in
size). The output size of dynamic libraries remained constant, but the output
size of rlibs increased, as seen below:
libarena - 2.27% bigger
libcollections - 0.64% bigger
libflate - 0.85% bigger
libfourcc - 14.67% bigger
libgetopts - 4.52% bigger
libglob - 2.74% bigger
libgreen - 9.68% bigger
libhexfloat - 13.68% bigger
liblibc - 10.79% bigger
liblog - 10.95% bigger
libnative - 8.34% bigger
libnum - 2.31% bigger
librand - 1.71% bigger
libregex - 6.43% bigger
librustc - 4.21% bigger
librustdoc - 8.98% bigger
librustuv - 4.11% bigger
libsemver - 2.68% bigger
libserialize - 1.92% bigger
libstd - 3.59% bigger
libsync - 3.96% bigger
libsyntax - 4.96% bigger
libterm - 13.96% bigger
libtest - 6.03% bigger
libtime - 2.86% bigger
liburl - 6.59% bigger
libuuid - 4.70% bigger
libworkcache - 8.44% bigger
This increase in size is a result of encoding many more section names into each
object file (rlib). These increases are moderate enough that this change seems
worthwhile to me, due to the drastic improvements seen in the final artifacts.
The overall increase of the stage2 target folder (not the size of an install)
went from 337MB to 348MB (3% increase).
Additionally, linking is generally slower when executed with all these new
sections plus the --gc-sections flag. The stage0 compiler takes 1.4s to link the
`rustc` binary, where the stage1 compiler takes 1.9s to link the binary. Three
megabytes are shaved off the binary. I found this increase in link time to be
acceptable relative to the benefits of code size gained.
This commit only enables --gc-sections for *executables*, not dynamic libraries.
LLVM does all the heavy lifting when producing an object file for a dynamic
library, so there is little else for the linker to do (remember that we only
have one object file).
I conducted similar experiments by putting a *module's* functions and data
symbols into its own section (granularity moved to a module level instead of a
function/static level). The size benefits of a hello world were seen to be on
the order of 400K rather than 1.2MB. It seemed that enough benefit was gained
using ffunction-sections that this route was less desirable, despite the lesser
increases in binary rlib size.
Also move prelude explanation to the prelude module.
This tries to provide a guide to what's in the standard library, organized bottom up from primitives to I/O.
There is currently not much precedent for target crates requiring syntax
extensions to compile their test versions. This dependency is possible, but
can't be encoded through the normal means of DEPS_regex because it is a
test-only dependency and it must be a *host* dependency (it's a syntax
extension).
Closes#13844
The compiler has previously been producing binaries on the order of 1.8MB for
hello world programs "fn main() {}". This is largely a result of the compilation
model used by compiling entire libraries into a single object file and because
static linking is favored by default.
When linking, linkers will pull in the entire contents of an object file if any
symbol from the object file is used. This means that if any symbol from a rust
library is used, the entire library is pulled in unconditionally, regardless of
whether the library is used or not.
Traditional C/C++ projects do not normally encounter these large executable
problems because their archives (rust's rlibs) are composed of many objects.
Because of this, linkers can eliminate entire objects from being in the final
executable. With rustc, however, the linker does not have the opportunity to
leave out entire object files.
In order to get similar benefits from dead code stripping at link time, this
commit enables the -ffunction-sections and -fdata-sections flags in LLVM, as
well as passing --gc-sections to the linker *by default*. This means that each
function and each global will be placed into its own section, allowing the
linker to GC all unused functions and data symbols.
By enabling these flags, rust is able to generate much smaller binaries default.
On linux, a hello world binary went from 1.8MB to 597K (a 67% reduction in
size). The output size of dynamic libraries remained constant, but the output
size of rlibs increased, as seen below:
libarena - 2.27% bigger ( 292872 => 299508)
libcollections - 0.64% bigger ( 6765884 => 6809076)
libflate - 0.83% bigger ( 186516 => 188060)
libfourcc - 14.71% bigger ( 307290 => 352498)
libgetopts - 4.42% bigger ( 761468 => 795102)
libglob - 2.73% bigger ( 899932 => 924542)
libgreen - 9.63% bigger ( 1281718 => 1405124)
libhexfloat - 13.88% bigger ( 333738 => 380060)
liblibc - 10.79% bigger ( 551280 => 610736)
liblog - 10.93% bigger ( 218208 => 242060)
libnative - 8.26% bigger ( 1362096 => 1474658)
libnum - 2.34% bigger ( 2583400 => 2643916)
librand - 1.72% bigger ( 1608684 => 1636394)
libregex - 6.50% bigger ( 1747768 => 1861398)
librustc - 4.21% bigger (151820192 => 158218924)
librustdoc - 8.96% bigger ( 13142604 => 14320544)
librustuv - 4.13% bigger ( 4366896 => 4547304)
libsemver - 2.66% bigger ( 396166 => 406686)
libserialize - 1.91% bigger ( 6878396 => 7009822)
libstd - 3.59% bigger ( 39485286 => 40902218)
libsync - 3.95% bigger ( 1386390 => 1441204)
libsyntax - 4.96% bigger ( 35757202 => 37530798)
libterm - 13.99% bigger ( 924580 => 1053902)
libtest - 6.04% bigger ( 2455720 => 2604092)
libtime - 2.84% bigger ( 1075708 => 1106242)
liburl - 6.53% bigger ( 590458 => 629004)
libuuid - 4.63% bigger ( 326350 => 341466)
libworkcache - 8.45% bigger ( 1230702 => 1334750)
This increase in size is a result of encoding many more section names into each
object file (rlib). These increases are moderate enough that this change seems
worthwhile to me, due to the drastic improvements seen in the final artifacts.
The overall increase of the stage2 target folder (not the size of an install)
went from 337MB to 348MB (3% increase).
Additionally, linking is generally slower when executed with all these new
sections plus the --gc-sections flag. The stage0 compiler takes 1.4s to link the
`rustc` binary, where the stage1 compiler takes 1.9s to link the binary. Three
megabytes are shaved off the binary. I found this increase in link time to be
acceptable relative to the benefits of code size gained.
This commit only enables --gc-sections for *executables*, not dynamic libraries.
LLVM does all the heavy lifting when producing an object file for a dynamic
library, so there is little else for the linker to do (remember that we only
have one object file).
I conducted similar experiments by putting a *module's* functions and data
symbols into its own section (granularity moved to a module level instead of a
function/static level). The size benefits of a hello world were seen to be on
the order of 400K rather than 1.2MB. It seemed that enough benefit was gained
using ffunction-sections that this route was less desirable, despite the lesser
increases in binary rlib size.
There is currently not much precedent for target crates requiring syntax
extensions to compile their test versions. This dependency is possible, but
can't be encoded through the normal means of DEPS_regex because it is a
test-only dependency and it must be a *host* dependency (it's a syntax
extension).
Closes#13844
The AST doesn't need ~s everywhere, so we can save allocations this way
& the enum isn't particularly large (~4 words) nor are regexes
long (normally), so the space saved in the `Cat` vector is unlikely to
be very much.
This flag to the linker asks it to strip away all dead code during linking, as
well as dead data. This reduces the size of hello world from 1.7MB to 458K on my
system (70% reduction).
I have not seen this impact link times negatively, and I have seen this pass
'make check' successfully. I am slightly wary of adding this option, but the
benefits are so huge tha I think we should work hard to work around any issues
rather than avoid using the flag entirely.
All links inside docblocks will have their color set to `#4e8bca` (a
light blue color to contrast against the black text). This color also
offers a visible contrast from the surrounding text if viewed as
grayscale, making it suitable for accessability.
Docblock links will also be underlined when hovered over.
Currently, in both chrome and firefox, if I type something in the search box in the reference docs I get immediately the search results. That's great. However, if I want to go back to the doc I was reading and try to press the back button, I am immediately forwarded again to the search results. This is caused by the fact that the search term is (deliberately) left in the search box, and the search() function is called as if I typed the search term again.
I disabled calling the search() function if there's no search term in the URL, and now it seems to work fine.
I hope I'm sending the pull request correctly - I'm not really used to git and github.
This commit deprecates rev_iter, mut_rev_iter, move_rev_iter everywhere (except treemap) and also
deprecates related functions like rsplit, rev_components, and rev_str_components. In every case,
these functions can be replaced with the non-reversed form followed by a call to .rev(). To make this
more concrete, a translation table for all functional changes necessary follows:
* container.rev_iter() -> container.iter().rev()
* container.mut_rev_iter() -> container.mut_iter().rev()
* container.move_rev_iter() -> container.move_iter().rev()
* sliceorstr.rsplit(sep) -> sliceorstr.split(sep).rev()
* path.rev_components() -> path.components().rev()
* path.rev_str_components() -> path.str_components().rev()
In terms of the type system, this change also deprecates any specialized reversed iterator types (except
in treemap), opting instead to use Rev directly if any type annotations are needed. However, since
methods directly returning reversed iterators are now discouraged, the need for such annotations should
be small. However, in those cases, the general pattern for conversion is to take whatever follows Rev in
the original reversed name and surround it with Rev<>:
* RevComponents<'a> -> Rev<Components<'a>>
* RevStrComponents<'a> -> Rev<StrComponents<'a>>
* RevItems<'a, T> -> Rev<Items<'a, T>>
* etc.
The reasoning behind this change is that it makes the standard API much simpler without reducing readability,
performance, or power. The presence of functions such as rev_iter adds more boilerplate code to libraries
(all of which simply call .iter().rev()), clutters up the documentation, and only helps code by saving two
characters. Additionally, the numerous type synonyms that were used to make the type signatures look nice
like RevItems add even more boilerplate and clutter up the docs even more. With this change, all that cruft
goes away.
[breaking-change]
This makes the splitting functions in std::slice return DoubleEndedIterators. Unfortunately,
splitn and rsplitn cannot provide such an interface and so must return different types. As a
result, the following changes were made:
* RevSplits was removed in favor of explicitly using Rev
* Splits can no longer bound the number of splits done
* Splits now implements DoubleEndedIterator
* SplitsN was added, taking the role of what both Splits and RevSplits used to be
* rsplit returns Rev<Splits<'a, T>> instead of RevSplits<'a, T>
* splitn returns SplitsN<'a, T> instead of Splits<'a, T>
* rsplitn returns SplitsN<'a, T> instead of RevSplits<'a, T>
All functions that were previously implemented on each return value still are, so outside of changing
of type annotations, existing code should work out of the box. In the rare case that code relied
on the return types of split and splitn or of rsplit and rsplitn being the same, the previous
behavior can be emulated by calling splitn or rsplitn with a bount of uint::MAX.
The value of this change comes in multiple parts:
* Consistency. The splitting code in std::str is structured similarly to the new slice splitting code,
having separate CharSplits and CharSplitsN types.
* Smaller API. Although this commit doesn't implement it, using a DoubleEndedIterator for splitting
means that rsplit, path::RevComponents, path::RevStrComponents, Path::rev_components, and
Path::rev_str_components are no longer needed - they can be emulated simply with .rev().
* Power. DoubleEndedIterators are able to traverse the list from both sides at once instead of only
forwards or backwards.
* Efficiency. For the common case of using split instead of splitn, the iterator is slightly smaller
and slightly faster.
[breaking-change]
Similar to my recent changes to ~[T]/&[T], these changes remove the vstore abstraction and represent str types as ~(str) and &(str). The Option<uint> in ty_str is the length of the string, None if the string is dynamically sized.
This flag to the linker asks it to strip away all dead code during linking, as
well as dead data. This reduces the size of hello world from 1.7MB to 458K on my
system (70% reduction).
I have not seen this impact link times negatively, and I have seen this pass
'make check' successfully. I am slightly wary of adding this option, but the
benefits are so huge tha I think we should work hard to work around any issues
rather than avoid using the flag entirely.
This PR is primarily motivated by (and fixes) #12926.
We currently only have a span for the individual item itself and not for the referred contents. This normally does not cause a problem since both are located in the same file; it *is* possible that the contained statement or item is located in the other file (the syntax extension can do that), but even in that case the syntax extension should be located in the same file as the item. The module item (i.e. `mod foo;`) is the only exception here, and thus warrants a special treatment.
Rustdoc would now distinguish `mod foo;` from `mod foo {...}` by checking if the span for the module item and module contents is in different files. If it's the case, we'd prefer module contents over module item. There are alternative strategies, but as noted above we will have some corner cases if we don't record the contents span explicitly.
Similar to my recent changes to ~[T]/&[T], these changes remove the vstore abstraction and represent str types as ~(str) and &(str). The Option<uint> in ty_str is the length of the string, None if the string is dynamically sized.
As of cc6ec8df, the Owned closures example uses println! instead of
debug!, making a note about seeing debug seem out-of-place in this
section.
Since debug! is not used elsewhere in the tutorial, remove the note
entirely.
