Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 31 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,39 @@
# usvfs
# USVFS

[![License](http://img.shields.io/:license-gpl-blue.svg)](http://www.gnu.org/licenses/gpl-3.0.en.html)
[![Build status](https://github.com/github/docs/actions/workflows/build.yml/badge.svg)](https://github.com/ModOrganizer2/usvfs/actions)
[![License](https://img.shields.io/:license-gpl-blue.svg)](http://www.gnu.org/licenses/gpl-3.0.en.html)
[![Build](https://github.com/ModOrganizer2/usvfs/actions/workflows/build.yml/badge.svg)](https://github.com/ModOrganizer2/usvfs/actions)

USVFS (short for User Space Virtual File System) aims to allow windows applications to create file or directory links that
are visible to only a select set of processes.
It does so by using api hooking to fool file access functions into discovering/opening files that are in fact somewhere else
USVFS (short for User Space Virtual File System) aims to allow windows applications to
create file or directory links that are visible to only a select set of processes.
It does so by using api hooking to fool file access functions into discovering/opening
files that are in fact somewhere else.

## Current state

USVFS is work in progress and should be considered in alpha state.
It is a core component of Mod Organizer v2 <https://github.com/ModOrganizer2/modorganizer>
and thus receives serious real world testing.

## Building

You will need `cmake`, Python 3+ and `vcpkg` to build USVFS:

```pwsh
cmake --preset vs2022-windows-x64
cmake --build --preset vs2022-windows-x64 --config Release

# only if you need to hook x86 applications
cmake --preset vs2022-windows-x86
cmake --build --preset vs2022-windows-x86 --config Release
```

## Comparison to symbolic links

The following is based on the final goal for usvfs and doesn't necessary reflect the current development state.
The following is based on the final goal for USVFS and doesn't necessary reflect the
current development state.

Unlike symbolic file links provided by NTFS

- links aren't visible to all applications but only to those the caller chooses
- links disappear when the "session ends"
- doesn't require write access to the link destination
Expand All @@ -21,32 +43,15 @@ Unlike symbolic file links provided by NTFS
- can also "virtually" unlink files, thus make them invisible to processes or replace existing files

There are of course drawbacks

- will always impose a memory and cpu overhead though hopefully those will be marginal
- becomes active only during the initialization phase of each process so it may not be active at the time dependent dlls are loaded
- introduces a new source of bugs that can cause hard to diagnose problems in affected processes
- may rub antivirus software the wrong way as the used techniques are similar to what some malware does.

## Current state

usvfs is work in progress and should be considered in alpha state.
It is a core component of Mod Organizer v2 <https://github.com/ModOrganizer2/modorganizer>
and thus receives serious real world testing

## Building

You will `cmake`, Python 3+ and `vcpkg` to build USVFS:

```pwsh
cmake -B build32 -A Win32 "-DCMAKE_TOOLCHAIN_FILE=path\to\vcpkg\scripts\buildsystems\vcpkg.cmake" -DBUILD_USVFS_TESTS=TRUE
cmake --build build32 --config Release

cmake -B build64 -A Win64 "-DCMAKE_TOOLCHAIN_FILE=path\to\vcpkg\scripts\buildsystems\vcpkg.cmake" -DBUILD_USVFS_TESTS=TRUE
cmake --build build64 --config Release
```

## License

usvfs is currently licensed under the GPLv3 but this may change in the future.
USVFS is currently licensed under the GPLv3 but this may change in the future.

## Contributing

Expand Down