Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Small docs improvements #231

Merged
merged 2 commits into from
Apr 8, 2019
Merged

Small docs improvements #231

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
98dfcb3
small docs improvements
manonthegithub Apr 8, 2019
c36ae80
Break lines to support narrow terminals
niklas88 Apr 8, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/native_setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Run ctest. All tests should pass:
ctest

## Create or reuse an index
See the main [README](README.md#create_or_reuse_an_index) but make sure to
See the main [README](../README.md#creating-an-index) but make sure to
either add `./build/` to your path or prefix all commands with `./` and that
`/index` and `/input` need to be the path to the index and input on your host.

Expand Down
3 changes: 3 additions & 0 deletions docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
The following instructions build an index from our Scientists Example Knowledge
Base.

**Note:** If you experience an error check the [troubleshooting](./troubleshooting.md) document
for known issues such as problems with Docker on Mac.

## Download and build QLever using `docker`

git clone --recursive https://github.com/ad-freiburg/QLever.git qlever
Expand Down
23 changes: 23 additions & 0 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,3 +76,26 @@ the query execution. We will evaluate if it's worth also externalizing SPO and
SOP permutations in this way to further reduce the RAM usage, or to let the user
decide which permutations shall be stored in which format.

## Note when using Docker on Mac or Windows

When building an index, QLever will create scratch space for on-disc sorting.
This space is allocated as a large 1 TB sparse file. On standard Linux file
systems such as Ext4 sparse files are optimized and this will only take as much
disk space as is actually used.

With some systems such as Docker on Mac or when using unsupported file
systems such as NTFS or APFS, this may lead to problems as these do not
properly support sparse files.

One possible error may be the following:

open() error on path=/index/scientists-stxxl.disk flags=16450, retrying without O_DIRECT.
Disk '/index/scientists-stxxl.disk' is allocated, space: 500000 MiB, I/O implementation: syscall queue=0 devid=0
terminate called after throwing an instance of 'foxxll::io_error'
what(): Error in void foxxll::ufs_file_base::_set_size(foxxll::file::offset_type) : ftruncate() path=/index/scientists-stxxl.disk fd=4 : No space left on device: iostream error
Aborted

While macOS including Docker on Mac is not supported there are some workarounds.
You can manually change the constant `static const size_t STXXL_DISK_SIZE_INDEX_BUILDER`
in [file](../src/global/Constants.h) or
you can try using a named volume instead of a path on the host.