| 1 |
(**************************************************************************) |
| 2 |
(* *) |
| 3 |
(* Copyright 2012-2019 OCamlPro *) |
| 4 |
(* Copyright 2012 INRIA *) |
| 5 |
(* *) |
| 6 |
(* All rights reserved. This file is distributed under the terms of the *) |
| 7 |
(* GNU Lesser General Public License version 2.1, with the special *) |
| 8 |
(* exception on linking described in the file LICENSE. *) |
| 9 |
(* *) |
| 10 |
(**************************************************************************) |
| 11 |
|
| 12 |
(** Bindings of lots of filesystem and system operations *) |
| 13 |
|
| 14 |
exception Command_not_found of string |
| 15 |
|
| 16 |
exception Permission_denied of string |
| 17 |
|
| 18 |
(** Exception raised when a computation in the current process |
| 19 |
fails. *) |
| 20 |
exception Internal_error of string |
| 21 |
|
| 22 |
(** Raise [Internal_error] *) |
| 23 |
val internal_error: ('a, unit, string, 'b) format4 -> 'a |
| 24 |
|
| 25 |
(** [with_tmp_dir fn] executes [fn] creates a temporary directory and |
| 26 |
passes its name to [fn]. The directory is alwasy removed on completion. *) |
| 27 |
val with_tmp_dir: (string -> 'a) -> 'a |
| 28 |
|
| 29 |
(** [in_tmp_dir fn] executes [fn] in a temporary directory. *) |
| 30 |
val in_tmp_dir: (unit -> 'a) -> 'a |
| 31 |
|
| 32 |
(** Returns true if the default verbose level for base commands (cp, mv, etc.) |
| 33 |
is reached *) |
| 34 |
val verbose_for_base_commands: unit -> bool |
| 35 |
|
| 36 |
(** {2 Filesystem management} *) |
| 37 |
|
| 38 |
(** Returns a directory name, in the temporary directory, composed by {i opam} |
| 39 |
(if [prefix] is not set), pid, and random number. *) |
| 40 |
val mk_temp_dir: ?prefix:string -> unit -> string |
| 41 |
|
| 42 |
(** [copy_file src dst] copies [src] to [dst]. Remove [dst] before the copy |
| 43 |
if it is a link. *) |
| 44 |
val copy_file: string -> string -> unit |
| 45 |
|
| 46 |
(** [copy_dir src dst] copies the contents of directory [src] into directory |
| 47 |
[dst], creating it if necessary, merging directory contents and ovewriting |
| 48 |
files otherwise *) |
| 49 |
val copy_dir: string -> string -> unit |
| 50 |
|
| 51 |
val mv: string -> string -> unit |
| 52 |
|
| 53 |
type install_warning = [ `Add_exe (* [.exe] had to be added *) |
| 54 |
| `Install_dll (* Installation of [.dll] to bin/libexec *) |
| 55 |
| `Install_script (* Installation of script on Windows *) |
| 56 |
| `Install_unknown (* Installation of unknown file to bin/libexec *) |
| 57 |
| `Cygwin (* Installation of a Cygwin-linked executable *) |
| 58 |
| `Msys2 (* Installation of a MSYS2-linked executable *) |
| 59 |
| `Tainted of [`Msys2 | `Cygwin] (* Installation of an executable which itself is linked to a Cygwin or MSYS2-linked library *) |
| 60 |
| `Cygwin_libraries (* Installation of a binary linked to a Cygwin library *) |
| 61 |
] |
| 62 |
(** Warnings which come from {!install} *) |
| 63 |
|
| 64 |
type install_warning_fn = string -> install_warning -> unit |
| 65 |
|
| 66 |
val default_install_warning : install_warning_fn |
| 67 |
(** The default warning function - displays a message on OpamConsole *) |
| 68 |
|
| 69 |
(** [install ?exec src dst] copies file [src] as file [dst] using [install]. |
| 70 |
If [exec], make the resulting file executable (otherwise, look at the |
| 71 |
permissions of the original file to decide). *) |
| 72 |
val install: ?warning:install_warning_fn -> ?exec:bool -> string -> string -> unit |
| 73 |
|
| 74 |
(** Checks if a file is an executable (regular file with execution |
| 75 |
permission) *) |
| 76 |
val is_exec: string -> bool |
| 77 |
|
| 78 |
val file_is_empty: string -> bool |
| 79 |
|
| 80 |
(** [link src dst] links [src] to [dst]. Remove [dst] if it is a file, |
| 81 |
not a directory. *) |
| 82 |
val link: string -> string -> unit |
| 83 |
|
| 84 |
(** [real_path p] returns the real path associated to [p]: [..] are |
| 85 |
expanded and relative paths become absolute. *) |
| 86 |
val real_path: string -> string |
| 87 |
|
| 88 |
(** Return the contents of a channel. *) |
| 89 |
val string_of_channel: in_channel -> string |
| 90 |
|
| 91 |
(** Raised when a file or directory can't be accessed (doesn't exist, |
| 92 |
bad permissions, etc.) *) |
| 93 |
exception File_not_found of string |
| 94 |
|
| 95 |
(** [read filename] returns the contents of [filename] (while taking an advisory |
| 96 |
read lock to prevent concurrent writes) *) |
| 97 |
val read: string -> string |
| 98 |
|
| 99 |
(** [write filename contents] write [contents] to [filename] (while taking an |
| 100 |
advisory write lock to prevent concurrent reads or writes) *) |
| 101 |
val write: string -> string -> unit |
| 102 |
|
| 103 |
(** [remove filename] removes [filename]. Works whether [filename] is |
| 104 |
a file or a directory *) |
| 105 |
val remove: string -> unit |
| 106 |
|
| 107 |
(** [remove_file filename] removes [filename]. Works only for normal |
| 108 |
files (or also at least for symlinks) *) |
| 109 |
val remove_file: string -> unit |
| 110 |
|
| 111 |
(** [remove_dir filename] removes [filename]. Works only for |
| 112 |
directory (not for symlinks or other files). *) |
| 113 |
val remove_dir: string -> unit |
| 114 |
|
| 115 |
(** Change the current working directory *) |
| 116 |
val chdir: string -> unit |
| 117 |
|
| 118 |
(** [in_dir dir fn] evaluates [fn] in the directory [dir] *) |
| 119 |
val in_dir: string -> (unit -> 'a) -> 'a |
| 120 |
|
| 121 |
(** Returns the list of files and directories in the given directory (full |
| 122 |
names) *) |
| 123 |
val ls: string -> string list |
| 124 |
|
| 125 |
(** [files_with_links dir] returns the files in the directory [dir]. |
| 126 |
Links simulating directory are ignored, others links are returned. *) |
| 127 |
val files_with_links: string -> string list |
| 128 |
|
| 129 |
(** [rec_files dir] returns the list of all files in [dir], |
| 130 |
recursively. |
| 131 |
Links behaving like directory are crossed. *) |
| 132 |
val rec_files: string -> string list |
| 133 |
|
| 134 |
(** Return the list of files in the current directory. *) |
| 135 |
val files: string -> string list |
| 136 |
|
| 137 |
(** Return the list of files in the current directory, inclduing any |
| 138 |
dangling symlinks. *) |
| 139 |
val files_all_not_dir: string -> string list |
| 140 |
|
| 141 |
(** [rec_dirs dir] return the list list of all directories recursively |
| 142 |
(going through symbolink links). *) |
| 143 |
val rec_dirs: string -> string list |
| 144 |
|
| 145 |
(** Return the list of directories in the current directory. *) |
| 146 |
val dirs: string -> string list |
| 147 |
|
| 148 |
val dir_is_empty: string -> bool |
| 149 |
|
| 150 |
(** [directories_with_links dir] returns the directories in the directory [dir]. |
| 151 |
Links pointing to directory are also returned. *) |
| 152 |
val directories_with_links: string -> string list |
| 153 |
|
| 154 |
(** OLD COMMAND API, DEPRECATED *) |
| 155 |
|
| 156 |
(** a command is a list of words *) |
| 157 |
type command = string list |
| 158 |
|
| 159 |
(** END *) |
| 160 |
|
| 161 |
(** Test whether the file is an archive, by looking as its extension *) |
| 162 |
val is_archive: string -> bool |
| 163 |
|
| 164 |
(** Create a directory. Do not fail if the directory already |
| 165 |
exist. *) |
| 166 |
val mkdir: string -> unit |
| 167 |
|
| 168 |
(** {2 File locking function} *) |
| 169 |
|
| 170 |
(** Unix file locks (mutable structure, to follow actual semantics) *) |
| 171 |
type lock |
| 172 |
|
| 173 |
(** The different kinds of unix advisory locks available (`Lock_none doesn't |
| 174 |
actually lock anything, or even create the lock file) *) |
| 175 |
type actual_lock_flag = [ `Lock_read | `Lock_write ] |
| 176 |
type lock_flag = [ `Lock_none | actual_lock_flag ] |
| 177 |
|
| 178 |
(** Dummy lock *) |
| 179 |
val lock_none: lock |
| 180 |
|
| 181 |
(** Raised when locks can't be acquired and [dontblock] was specified) *) |
| 182 |
exception Locked |
| 183 |
|
| 184 |
(** Force releases all open locks in the process. Required for Windows if an exception |
| 185 |
has been raised, since Windows doesn't permit unlinking while handles are open. *) |
| 186 |
val release_all_locks: unit -> unit |
| 187 |
|
| 188 |
(** Acquires a lock on the given file. |
| 189 |
Raises [Locked] if the lock can't be acquired and [dontblock] is set. Raises |
| 190 |
[OpamStd.Sys.Exit] if [safe_mode] is set and a write lock is required. Also |
| 191 |
raises Unix errors if the lock file can't be opened. *) |
| 192 |
val flock: [< lock_flag ] -> ?dontblock:bool -> string -> lock |
| 193 |
|
| 194 |
(** Updates an existing lock to the given level. Raises the same exceptions as |
| 195 |
[flock]. *) |
| 196 |
val flock_update: [< lock_flag ] -> ?dontblock:bool -> lock -> unit |
| 197 |
|
| 198 |
(** Releases an acquired lock (equivalent to [flock_update `Lock_none]) *) |
| 199 |
val funlock: lock -> unit |
| 200 |
|
| 201 |
(** Returns the highest of the two lock flags (with the order no lock < read |
| 202 |
lock < write lock) *) |
| 203 |
val lock_max: lock_flag -> lock_flag -> lock_flag |
| 204 |
|
| 205 |
(** Returns true if the lock already has the lock_flag rights or more *) |
| 206 |
val lock_isatleast: [< lock_flag ] -> lock -> bool |
| 207 |
|
| 208 |
(** Returns the current kind of the lock *) |
| 209 |
val get_lock_flag: lock -> lock_flag |
| 210 |
|
| 211 |
(** Returns the underlying fd for the lock or raises Not_found for `No_lock *) |
| 212 |
val get_lock_fd: lock -> Unix.file_descr |
| 213 |
|
| 214 |
(** {2 Misc} *) |
| 215 |
|
| 216 |
(** Returns the end-of-line encoding style for the given file. [None] means that |
| 217 |
either the encoding of line endings is mixed, or the file contains no line |
| 218 |
endings at all (an empty file, or a file with one line and no EOL at EOF). |
| 219 |
Otherwise it returns [Some true] if all endings are encoded CRLF. *) |
| 220 |
val get_eol_encoding : string -> bool option |
| 221 |
|
| 222 |
(** [translate_patch ~dir input_patch output_patch] writes a copy of |
| 223 |
[input_patch] to [output_patch] as though [input_patch] had been applied in |
| 224 |
[dir]. The patch is rewritten such that if text files have different line |
| 225 |
endings then the patch is transformed to patch using the encoding on disk. |
| 226 |
In particular, this means that patches generated against Unix checkouts of |
| 227 |
Git sources will correctly apply to Windows checkouts of the same sources. |
| 228 |
*) |
| 229 |
val translate_patch: dir:string -> string -> string -> unit |
| 230 |
|
| 231 |
(** Create a temporary file in {i ~/.opam/logs/<name>XXX}, if [dir] is not set. |
| 232 |
?auto_clean controls whether the file is automatically deleted when opam |
| 233 |
terminates (default: [true]). *) |
| 234 |
val temp_file: ?auto_clean:bool -> ?dir:string -> string -> string |
| 235 |
|
| 236 |
(** Print stats *) |
| 237 |
val print_stats: unit -> unit |
| 238 |
|
| 239 |
(** Registers an exception printer that adds some OPAM version info, and details |
| 240 |
on process and Unix errors *) |
| 241 |
val register_printer: unit -> unit |
| 242 |
|
| 243 |
(** Initialises signal handlers, catch_break and some exception printers. The |
| 244 |
lib may not perform properly without this if [Sys.catch_break] isn't set |
| 245 |
and SIGPIPE isn't handled (with a no-op) *) |
| 246 |
val init: unit -> unit |
| 247 |
|
| 248 |
(** On Unix, a no-op. On Windows, convert / to \ *) |
| 249 |
val forward_to_back : string -> string |
| 250 |
|
| 251 |
(** On Unix, a no-op. On Windows, convert \ to / *) |
| 252 |
val back_to_forward : string -> string |
| 253 |
|
| 254 |
(** Identifies kinds of executable files. At present, only useful on Windows. |
| 255 |
Executable or DLLs are recognised based on their content, not on their |
| 256 |
filename. Any file beginning "#!" is assumed to be a shell script and all |
| 257 |
files are classified [`Unknown]. *) |
| 258 |
val classify_executable : string -> [ `Exe of [ `i386 | `x86 | `x86_64 ] |
| 259 |
| `Dll of [ `x86 | `x86_64 ] |
| 260 |
| `Script |
| 261 |
| `Unknown ] |