Installation¶
Stable release¶
$ pip install svfsc
This is the preferred method to install svfsc
, as it will always install the most recent stable release.
If you don’t have pip installed, this Python installation guide can guide you through the process.
From sources¶
The sources for svfsc
can be downloaded from the Github repo.
You can either clone the public repository:
$ git clone git://github.com/paulross/svfsc
Or download the tarball:
$ curl -OL https://github.com/paulross/svfsc/tarball/master
Once you have a copy of the source, create a virtual environment of your choice:
$ python3 -m venv <your_virtual_environment_directory>
$ source <your_virtual_environment_directory>/bin/activate
$ pip install -r requirements.txt
$ python setup.py install
Or for development, change the last line to:
$ python setup.py develop
Dependencies¶
psutil
for memory monitoring.pytest
and ancillary libraries for testing.sphinx
for documentation.
See requirements.txt
for the specific dependencies.
Building for C++¶
Consult the CMakeLists.txt
at the project root for how to do this. The build target is cppSVF
.
Build and Test¶
Typically a release build is done with:
cmake --build cmake-build-release --target cppSVF -- -j 6
The executable is in cmake-build-release/cppSVF
.
Executing that will run all the C++ tests, the exit code will be zero on success, non-zero if any test fails.
Dependencies¶
stdlib
Python
Incorporating SVF Into Your C++ Project¶
If you want to include SVF into your C++ project your CMakeLists.txt
should include:
add_executable(
<your_project>
# ...
# Version information
src/cpp/cpp_svfs.h
src/cpp/cpp_svfs.cpp
# The Sparse Virtual File
src/cpp/svf.h
src/cpp/svf.cpp
# The Sparse Virtual File System
src/cpp/svfs.h
src/cpp/svfs.cpp
# ...
)
include_directories(
# ...
src/cpp
# ...
)
Using SVF in your C++ Project¶
To use a SVF in your C++ code:
#include "svf.h"
// File modification time of 1672574430.0 (2023-01-01 12:00:30)
SVFS::SparseVirtualFile svf("Some file ID", 1672574430.0);
// Write six char at file position 14
svf.write(14, "ABCDEF", 6);
// Read from it
char read_buffer[2];
svf.read(16, 2, read_buffer);
// read_buffer now contains "CD"
// What do I have to do to read 24 bytes from file position 8?
// This returns a std::vector<std::pair<size_t, size_t>>
// as ((file_position, read_length), ...)
auto need = svf.need(8, 24);
// The following prints ((8, 6), (20, 4),)
std::cout << "(";
for (auto &val: need) {
std::cout << "(" << val.first << ", " << val.second << "),";
}
std::cout << ")" << std::endl;
To use a SVFS in your C++ code:
#include "svfs.h"
SVFS::SparseVirtualFileSystem svfs;
std::string id = "Some file ID";
// Add a SVF with a modification time of 1672574430.0 (2023-01-01 12:00:30)
svfs.insert(id, 1672574430.0);
// Write six char at file position 14
// .at() will throw a SVFS::Exceptions::ExceptionSparseVirtualFileSystemOutOfRange
// If the id is not in the SVFS.
svfs.at(id).write(14, "ABCDEF", 6);
// Read from it
char read_buffer[2];
svfs.at(id).read(16, 2, read_buffer);
// read_buffer now contains "CD"
// What do I have to do to read 24 bytes from file "Some file ID" in position 8?
// This returns a std::vector<std::pair<size_t, size_t>>
// as ((file_position, read_length), ...)
auto need = svfs.at(id).need(8, 24);
// The following prints ((8, 6), (20, 4),)
std::cout << "(";
for (auto &val: need) {
std::cout << "(" << val.first << ", " << val.second << "),";
}
std::cout << ")" << std::endl;
Building the Documentation¶
Prerequisites are Sphinx and Doxygen (and Latex for the PDF documentation). The complete documentation can be built thus:
$ cd docs
$ ./build_docs.sh
The HTML documentation, which includes the Doxygen documentation, is here:
$ open Sphinx/build/html/index.html
The Doxygen HTML documentation is here:
$ open Sphinx/build/html/_static/doxygen_html/index.html
The PDF documentation, which does not include the Doxygen documentation, is here:
$ open Sphinx/build/latex/svfsc.pdf
Release Checklist¶
On Your Development/Version Branch¶
Update the version in these places:
src/cpp/cpp_svfs.cpp
setup.cfg
setup.py
docs/SVFS.dox
docs/Sphinx/source/conf.py
HISTORY.rst and include description of the release.
And the version tests:
src/cpp/tests/test_cpp_svfs.cpp
tests/unit/test_svf.py
Run all builds, tests and documentation:
$ ./build_all.sh
Merge, Tag, Branch, Upload¶
Merge with master.
Merge master to your development branch if the work is done on a release branch.
Tag with version number.
Create new branch “major.minor” if a major or minor release.
Push all of that.
Upload to PyPi.