diff options
| -rw-r--r-- | CMakeLists.txt | 5 | ||||
| -rw-r--r-- | Doxyfile | 38 | ||||
| -rw-r--r-- | doc/Makefile | 20 | ||||
| -rw-r--r-- | doc/requirements.txt | 13 | ||||
| -rw-r--r-- | doc/src/api.rst | 7 | ||||
| -rw-r--r-- | doc/src/conf.py | 49 | ||||
| -rw-r--r-- | doc/src/extfs.rst | 5 | ||||
| -rw-r--r-- | doc/src/index.rst | 15 | ||||
| -rw-r--r-- | include/fs/extfs.hpp | 31 | ||||
| -rw-r--r-- | src/extsh.cpp | 2 | ||||
| -rw-r--r-- | src/fs/extfs.cpp | 2 |
11 files changed, 179 insertions, 8 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index 11db086..43bd0e4 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,8 @@ cmake_minimum_required(VERSION 3.2) -project("extfs" CXX) +project("extfs" + LANGUAGES CXX + VERSION 1.0 + ) list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules/") diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..6dc28ee --- /dev/null +++ b/Doxyfile @@ -0,0 +1,38 @@ +DOXYFILE_ENCODING = UTF-8 +QUIET = YES +PROJECT_NAME = extfs +PROJECT_NUMBER = 1.0.0 +PROJECT_BRIEF = "A C++ library for working with ext* family file systems" +OUTPUT_DIRECTORY = build/ +OUTPUT_LANGUAGE = English +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +FULL_PATH_NAMES = NO +TAB_SIZE = 2 +OPTIMIZE_OUTPUT_FOR_C = NO +IDL_PROPERTY_SUPPORT = NO +INPUT = include/fs +FILE_PATTERNS = *.hpp +RECURSIVE = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +PREDEFINED = +ALIASES += "rst=@verbatim embed:rst:leading-asterisk" +ALIASES += "endrst=@endverbatim" +HIDE_SCOPE_NAMES = YES +EXTRACT_PRIVATE = NO +QUIET = YES diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..69a0496 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = extfs +SOURCEDIR = src +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..5b391f4 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,13 @@ +alabaster==0.7.9 +Babel==2.3.4 +breathe==4.4.0 +docutils==0.13.1 +imagesize==0.7.1 +Jinja2==2.8 +MarkupSafe==0.23 +Pygments==2.1.3 +pytz==2016.10 +six==1.10.0 +snowballstemmer==1.2.1 +Sphinx==1.4.9 +sphinx-rtd-theme==0.1.9 diff --git a/doc/src/api.rst b/doc/src/api.rst new file mode 100644 index 0000000..3b2cec2 --- /dev/null +++ b/doc/src/api.rst @@ -0,0 +1,7 @@ +The API +======= + +.. toctree:: + :maxdepth: 1 + + extfs diff --git a/doc/src/conf.py b/doc/src/conf.py new file mode 100644 index 0000000..a67aee4 --- /dev/null +++ b/doc/src/conf.py @@ -0,0 +1,49 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +import os +import sys +import subprocess + +subprocess.call('cd ../../ && doxygen', shell=True) + +html_theme = 'sphinx_rtd_theme' + +extensions = ['breathe'] + +breathe_projects = {'extfs': os.path.abspath('../../build/xml') } +breathe_default_project = 'extfs' + +source_suffix = '.rst' +master_doc = 'index' + +project = 'extfs' +copyright = '2016, Felix Morgner' +author = 'Felix Morgner' + +version = '1.0.0' +release = '1.0.0' + +language = 'en' + +exclude_patterns = [ + 'build', + 'Thumbs.db', + '.DS_Store', + 'ext/breathe', +] + +pygments_style = 'sphinx' + +todo_include_todos = False + +htmlhelp_basename = 'extfsdoc' + +man_pages = [ + (master_doc, 'extfs', 'extfs Documentation', + [author], 1) +] + +rst_epilog = '.. |project_name| replace:: **%s**' % project + +primary_domain = 'cpp' diff --git a/doc/src/extfs.rst b/doc/src/extfs.rst new file mode 100644 index 0000000..d8f1f5a --- /dev/null +++ b/doc/src/extfs.rst @@ -0,0 +1,5 @@ +File System Access +================== + +.. doxygenstruct:: fs::extfs + :members: diff --git a/doc/src/index.rst b/doc/src/index.rst new file mode 100644 index 0000000..dee63dd --- /dev/null +++ b/doc/src/index.rst @@ -0,0 +1,15 @@ +Welcome to extfs's documentation! +================================= + +|project_name| is a simple, pure C++ implementation of the ext* family of file +systems. It provides a simple API to inspect, traverse and modify ext2/3/4 +file systems. |project_name| is designed to be included directly in the build +process of other projects, that why no binary builds are provided. + +User documentation +------------------ + +.. toctree:: + :maxdepth: 2 + + api diff --git a/include/fs/extfs.hpp b/include/fs/extfs.hpp index 0075572..6430fe2 100644 --- a/include/fs/extfs.hpp +++ b/include/fs/extfs.hpp @@ -9,27 +9,48 @@ namespace fs { + /** + * @brief The ext* file system + * + * This abstraction provides a top-level interface to an ext* family file system. It grants access to information like the + * size of the file system, the space left on the file system as well as the label. + * + * @since 1.0 + */ struct extfs { + /** + * @brief How to open the file system + * + * @since 1.0 + */ enum struct mode : char { - read_only, - writeable + read_only, ///< Open in read-only mode + writeable, ///< Open in read-write mode }; /** - * Open the filesystem at a given path + * @brief Open the filesystem at a given path * * @param path The path to a device/file containing an ext* file system. * @param openMode Whether to open the file system in read_only or writeable mode. + * * @since 1.0 + * + * @note This call will also succeed if the file system could not be opened for some reason. To check whether the file + * system was successfully opened, see #fs::extfs::open(). */ explicit extfs(std::string const & path, mode const openMode = mode::read_only); /** - * Check if the filesystem is valid + * @brief Check if the filesystem is open. + * + * @return @p true, iff. the file system is opened, @p false otherwise + * + * @since 1.0 */ - operator bool() const; + bool open() const; private: std::fstream m_stream{}; diff --git a/src/extsh.cpp b/src/extsh.cpp index 477f6c8..87df7d3 100644 --- a/src/extsh.cpp +++ b/src/extsh.cpp @@ -8,7 +8,7 @@ int main(int argc, char const * argv[]) auto const & path = [&]{ return std::string{argc > 1 ? argv[1] : "vdisk.img"}; }(); auto const & disk = fs::extfs{path}; - if(disk) + if(disk.open()) { std::clog << "[EXT2] Successfully opened ext*fs at: '" << path << "'\n"; } diff --git a/src/fs/extfs.cpp b/src/fs/extfs.cpp index 19c294b..55cffd8 100644 --- a/src/fs/extfs.cpp +++ b/src/fs/extfs.cpp @@ -27,7 +27,7 @@ namespace fs read_superblock(m_stream, m_primarySuperblock); } - extfs::operator bool() const + bool extfs::open() const { return m_stream && m_primarySuperblock.magic_number == kExtfsMagic; } |