Representation of paths
The aim of this module is to provide a solid basis to reason about file and directory paths inside the Dune code base. What it is not is a complete API for paths management that handles all the aspects of file system paths. It simply exposes a high-level and portable API that covers the needs of Dune.
Dune sees the file system as two parts. The first part is composed of the source tree and the build directory. In this part, Dune doesn't know about symlinks and has a fully expanded view of the file system. This means that if the user has a symlink `src/foo` pointing to `bar`, then `src/foo/x` and `bar/x` are seen as two different paths.
A path in this world is called a local path and is simply a sequence of path components. A path component being a string other than "." or ".." and not containing the path separator character ('/').
Such a path can be rooted at the source tree root, the build directory or an unspecified root. All these paths are represented by values of type
'a Path.Local_gen.t where
'a denotes the root of the path.
The second part is the "external world". It is all the paths that live outside of the workspace and build directory. To be on the safe side Dune makes no assumption does nothing clever with these paths.
External paths are represented as
Path.t type represents all possible paths, i.e. both local and external paths.
module Local_gen : sig ... end
Relative path relative to the root tracked by the type system.
module Unspecified : sig ... end
module Local : sig ... end
Relative path with unspecified root.
module External : sig ... end
module Source : sig ... end
In the source section of the current workspace.
module Permissions : sig ... end
module Outside_build_dir : sig ... end
module Build : sig ... end
val to_string : t -> string
val of_string : string -> t
val parse_string_exn : loc:Stdune__.Loc0.t -> string -> t
a directory is smaller than its descendants
val extension : t -> string
map_extension path ~f replaces extension of
module Set : sig ... end
module Table : sig ... end
Specialized tables for path. We do implement all of
Hashtbl_intf.S - only what we use in dune.
val hash : t -> int
val to_string_maybe_quoted : t -> string
to_string_maybe_quoted t is
maybe_quoted (to_string t)
val root : t
val is_root : t -> bool
val is_managed : t -> bool
val relative_to_source_in_build_or_external : ?error_loc:Stdune__.Loc0.t -> dir:Build.t -> string -> t
relative_to_source_in_build ~dir s compute the path
s relative to the source directory corresponding to
val of_filename_relative_to_initial_cwd : string -> t
Create an external path. If the argument is relative, assume it is relative to the initial directory dune was launched in.
val to_absolute_filename : t -> string
Convert a path to an absolute filename. Must be called after the workspace root has been set.
root is the root directory of local paths
Reach a given path
from a directory. For example, let
p be a path to the file
d be a path to the directory
reach p ~from:d evaluates to
extend_basename p ~suffix adds
suffix at the end of the path
Extract the build context from a path. For instance, representing paths as strings:
extract_build_context "_build/blah/foo/bar" = Some ("blah", "foo/bar")
It doesn't work correctly (doesn't return a sensible source path) for build directories that are not build contexts, e.g. "_build/install" and "_build/.aliases".
extract_build_context but return the build context as a path:
extract_build_context "_build/blah/foo/bar" = Some ("_build/blah", "foo/bar")
Drop the "_build/blah" prefix if present, return
Drop the "_build/blah" prefix if present, return
t if it's a source file, otherwise fail.
val build_dir : t
The build directory
val is_in_build_dir : t -> bool
is_in_build_dir t = is_descendant t ~of:build_dir
val is_in_source_tree : t -> bool
is_in_source_tree t = is_managed t && not (is_in_build_dir t)
val is_strict_descendant_of_build_dir : t -> bool
is_strict_descendant_of_build_dir t = is_in_build_dir t && t <> build_dir
Split after the first component if
t is local
val exists : t -> bool
val is_directory : t -> bool
is_dir t checks if
t is a directory. It swallows permission errors so the preferred way is to use
val rmdir : t -> unit
val rm_rf : ?allow_external:bool -> t -> unit
If the path does not exist, this function is a no-op.
clear_dir t deletes all the contents of directory
t without removing
val mkdir_p : ?perms:int -> t -> unit
val in_source : string -> t
paths guaranteed to be in the source directory
val set_root : External.t -> unit
Set the workspace root. Can only be called once and the path must be absolute
module L : sig ... end
Return the "local part" of a path. For local paths (in build directory or source tree), this returns the path itself. For external paths, it returns a path that is relative to the current directory. For example, the local part of
Rename a file.
rename oldpath newpath renames the file called
newpath, moving it between directories if needed. If
newpath already exists, its contents will be replaced with those of
val chmod : t -> mode:int -> unit
Set permissions for a given path. You can use the
Permissions module if you need to modify existing permissions in a non-trivial way.
Attempts to resolve a symlink. Returns
None if the path isn't a symlink
drop_prefix_exn t ~prefix drops the
prefix from a path, including any leftover `/` prefix. Raises a
Code_error.t if the prefix wasn't found.
drop_prefix t ~prefix drops the
prefix from a path, including any leftover `/` prefix. Returns
None if the prefix wasn't found.
module Expert : sig ... end