Debian Codegraph @

vendor/opam/src/core/opamSystem.mli

raw
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 ]