Path (u.2be480bd288e68619424b01b6f16ce5f.stdune.3.18.2.doc.stdune.Stdune.Path)

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.

Model of the file system

Local paths

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.

External paths

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.External.t values.

The Path.t type

The 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

type t = private

| External of External.t
| In_source_tree of Source.t
| In_build_dir of Build.t

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

include Comparator.S with type t := t

val compare : t -> t -> Ordering.t

include Comparator.OPS with type t := t

val (=) : t -> t -> bool

val (>=) : t -> t -> bool

val (>) : t -> t -> bool

val (<=) : t -> t -> bool

val (<) : t -> t -> bool

val (<>) : t -> t -> bool

val to_dyn : t -> Dyn.t

val extension : t -> string

val set_extension : t -> ext:string -> t

set_extension path ~ext replaces extension of path by ext

val map_extension : t -> f:(string -> string) -> t

map_extension path ~f replaces extension of path by f extension

val split_extension : t -> t * string

val basename : t -> Filename.t

val basename_opt : t -> Filename.t option

module Map : Map.S with type key = t

module Set : sig ... end

val relative : ?error_loc:Stdune__.Loc0.t -> t -> string -> t

val parent_exn : t -> t

val parent : t -> t option

module Table : sig ... end

Specialized tables for path. We do implement all of Hashtbl_intf.S - only what we use in dune.

val equal : t -> t -> bool

val as_outside_build_dir : t -> Outside_build_dir.t option

val as_outside_build_dir_exn : t -> Outside_build_dir.t

val destruct_build_dir : 
  t ->
  [ `Inside of Build.t | `Outside of Outside_build_dir.t ]

val outside_build_dir : Outside_build_dir.t -> t

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 external_ : External.t -> 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 dir

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

val pp : t -> _ Pp.t

val reach : t -> from:t -> string

Reach a given path from a directory. For example, let p be a path to the file some/dir/file and d be a path to the directory some/another/dir. Then reach p ~from:d evaluates to ../../dir/file.

val reach_for_running : ?from:t -> t -> string

from defaults to Path.root

val descendant : t -> of_:t -> t option

val is_descendant : t -> of_:t -> bool

val append_local : t -> Local.t -> t

val append_source : t -> Source.t -> t

val extend_basename : t -> suffix:Filename.t -> t

extend_basename p ~suffix adds suffix at the end of the path

val extract_build_context : t -> (Filename.t * Source.t) option

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".

val extract_build_context_exn : t -> Filename.t * Source.t

val extract_build_context_dir : t -> (t * Source.t) option

Same as extract_build_context but return the build context as a path:

  extract_build_context "_build/blah/foo/bar" = Some ("_build/blah", "foo/bar")

val extract_build_context_dir_maybe_sandboxed : t -> (t * Source.t) option

val extract_build_context_dir_exn : t -> t * Source.t

val drop_build_context : t -> Source.t option

Drop the "_build/blah" prefix

val drop_build_context_exn : t -> Source.t

val drop_optional_build_context : t -> t

Drop the "_build/blah" prefix if present, return t otherwise

val drop_optional_build_context_maybe_sandboxed : t -> t

val drop_optional_sandbox_root : t -> t

val drop_optional_build_context_src_exn : t -> Source.t

Drop the "_build/blah" prefix if present, return t if it's a source file, otherwise fail.

val explode : t -> Filename.t list option

val explode_exn : t -> Filename.t list

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 as_in_source_tree : t -> Source.t option

val as_in_source_tree_exn : t -> Source.t

val as_in_build_dir : t -> Build.t option

val as_in_build_dir_exn : t -> Build.t

val as_external : t -> External.t option

val is_strict_descendant_of_build_dir : t -> bool

is_strict_descendant_of_build_dir t = is_in_build_dir t && t <> build_dir

val split_first_component : t -> (Filename.t * t) option

Split after the first component if t is local

val exists : t -> bool

val readdir_unsorted : 
  t ->
  (Filename.t list, Dune_filesystem_stubs.Unix_error.Detailed.t) Result.t

val readdir_unsorted_with_kinds : 
  t ->
  ((Filename.t * Unix.file_kind) list,
    Dune_filesystem_stubs.Unix_error.Detailed.t)
    Result.t

val is_dir_sep : char -> 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 stat instead

val rmdir : t -> unit

val unlink_exn : t -> unit

val unlink_no_err : t -> unit

val link : t -> t -> unit

val rm_rf : ?allow_external:bool -> t -> unit

If the path does not exist, this function is a no-op.

val clear_dir : t -> Fpath.clear_dir_result

clear_dir t deletes all the contents of directory t without removing t itself.

val mkdir_p : ?perms:int -> t -> unit

val build_dir_exists : unit -> bool

val ensure_build_dir_exists : unit -> unit

val source : Source.t -> t

val build : Build.t -> t

val in_source : string -> t

paths guaranteed to be in the source directory

val of_local : Local.t -> t

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

val local_part : t -> Local.t

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 /a/b is ./a/b.

val stat : 
  t ->
  (Unix.stats, Dune_filesystem_stubs.Unix_error.Detailed.t) Result.t

val stat_exn : t -> Unix.stats

val lstat : 
  t ->
  (Unix.stats, Dune_filesystem_stubs.Unix_error.Detailed.t) Result.t

val lstat_exn : t -> Unix.stats

val set_of_source_paths : Source.Set.t -> Set.t

val set_of_build_paths_list : Build.t list -> Set.t

val set_of_external_paths : External.Set.t -> Set.t

val rename : t -> t -> unit

Rename a file. rename oldpath newpath renames the file called oldpath to newpath, moving it between directories if needed. If newpath already exists, its contents will be replaced with those of oldpath.

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.

val follow_symlink : t -> (t, Fpath.follow_symlink_error) result

Attempts to resolve a symlink. Returns:

Ok path with the resolved destination
Error Not_a_symlink if the path isn't a symlink
Error Max_depth_exceeded if the function reached the maximum symbolic link depth
Error (Unix_error _) with the underlying syscall error.

val drop_prefix_exn : t -> prefix:t -> Local.t

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.

val drop_prefix : t -> prefix:t -> Local.t option

drop_prefix t ~prefix drops the prefix from a path, including any leftover `/` prefix. Returns None if the prefix wasn't found.

val make_local_path : Local.t -> t

module Expert : sig ... end