Debian Codegraph @

vendor/opam/src/format/opamFile.mli

raw
1 (**************************************************************************)
2 (* *)
3 (* Copyright 2012-2020 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 (** Handles all OPAM file formats as record types and submodules, conversion to
13 and from syntax *)
14
15 open OpamParserTypes.FullPos
16 open OpamTypes
17
18 (** Functions to read and write OPAM configuration files in a typed way *)
19
20 (** Associate a type to a filename through a phantom type *)
21 type 'a t = private filename
22
23 type 'a typed_file = 'a t
24
25 val make: filename -> 'a t
26 val filename: 'a t -> filename
27 val to_string: 'a t -> string
28 val exists: 'a t -> bool
29
30 (** All Configuration files satisfy this signature *)
31 module type IO_FILE = sig
32
33 (** File contents *)
34 type t
35
36 val format_version: OpamVersion.t
37
38 (** Empty file *)
39 val empty: t
40
41 (** Write some contents to a file *)
42 val write: t typed_file -> t -> unit
43
44 (** Read file contents. Raise an error if the file does not exist. *)
45 val read: t typed_file -> t
46
47 (** Returns [None] on non-existing file *)
48 val read_opt: t typed_file -> t option
49
50 (** Read file contents. Return [empty] if the file does not exist. *)
51 val safe_read: t typed_file -> t
52
53 val read_from_channel: ?filename:t typed_file -> in_channel -> t
54
55 val read_from_string: ?filename:t typed_file -> string -> t
56
57 val write_to_channel: ?filename:t typed_file -> out_channel -> t -> unit
58
59 val write_to_string: ?filename:t typed_file -> t -> string
60
61 end
62
63 (* Error less [IO_FILE] read functions. *)
64 module type BestEffortRead = sig
65 type t
66 val read: t typed_file -> t
67 val read_opt: t typed_file -> t option
68 val safe_read: t typed_file -> t
69 val read_from_channel: ?filename:t typed_file -> in_channel -> t
70 val read_from_string: ?filename:t typed_file -> string -> t
71 end
72
73 (** Lines of space-separated words. *)
74 module Lines: IO_FILE with type t = string list list
75
76 (** Command wrappers for package scripts *)
77 module Wrappers: sig
78 type t = {
79 pre_build : command list;
80 wrap_build : command list;
81 post_build : command list;
82 pre_install : command list;
83 wrap_install : command list;
84 post_install : command list;
85 pre_remove : command list;
86 wrap_remove : command list;
87 post_remove : command list;
88 pre_session : command list;
89 post_session : command list;
90 }
91
92 val pre_build: t -> command list
93 val wrap_build: t -> command list
94 val post_build: t -> command list
95 val pre_install: t -> command list
96 val wrap_install: t -> command list
97 val post_install: t -> command list
98 val pre_remove: t -> command list
99 val wrap_remove: t -> command list
100 val post_remove: t -> command list
101 val pre_session: t -> command list
102 val post_session: t -> command list
103
104 val with_pre_build: command list -> t -> t
105 val with_wrap_build: command list -> t -> t
106 val with_post_build: command list -> t -> t
107 val with_pre_install: command list -> t -> t
108 val with_wrap_install: command list -> t -> t
109 val with_post_install: command list -> t -> t
110 val with_pre_remove: command list -> t -> t
111 val with_wrap_remove: command list -> t -> t
112 val with_post_remove: command list -> t -> t
113 val with_pre_session: command list -> t -> t
114 val with_post_session: command list -> t -> t
115
116 val empty : t
117
118 val add: outer:t -> inner:t -> t
119 end
120
121 (** Configuration file: [$opam/config] *)
122 module Config: sig
123
124 include IO_FILE
125
126 (** Current root version *)
127 val root_version: opam_version
128
129 (** OCaml switch updates *)
130 val with_switch: switch -> t -> t
131 val with_switch_opt: switch option -> t -> t
132
133 (** The list of switches, ordered by most recently used first *)
134 val with_installed_switches: switch list -> t -> t
135
136 (** Repository updates *)
137 val with_repositories: repository_name list -> t -> t
138
139 (** Update opam-version *)
140 val with_opam_version: OpamVersion.t -> t -> t
141 val with_opam_root_version: OpamVersion.t -> t -> t
142
143 val with_criteria: (solver_criteria * string) list -> t -> t
144 val with_best_effort_prefix: string -> t -> t
145 val with_best_effort_prefix_opt: string option-> t -> t
146
147 val with_solver: arg list -> t -> t
148 val with_solver_opt: arg list option -> t -> t
149
150 val with_jobs: int -> t -> t
151 val with_jobs_opt: int option -> t -> t
152 val with_dl_tool: arg list -> t -> t
153 val with_dl_tool_opt: arg list option -> t -> t
154 val with_dl_jobs: int -> t -> t
155 val with_dl_cache: url list -> t -> t
156
157 val with_wrappers: Wrappers.t -> t -> t
158 val with_global_variables:
159 (variable * variable_contents * string) list -> t -> t
160 val with_eval_variables:
161 (variable * string list * string) list -> t -> t
162 val with_validation_hook_opt:
163 arg list option -> t -> t
164 val with_default_compiler:
165 formula -> t -> t
166 val with_default_invariant:
167 formula -> t -> t
168 val with_depext: bool -> t -> t
169 val with_depext_run_installs: bool -> t -> t
170 val with_depext_cannot_install: bool -> t -> t
171 val with_depext_bypass: OpamSysPkg.Set.t -> t -> t
172 val with_sys_pkg_manager_cmd: filename OpamStd.String.Map.t -> t -> t
173
174 val with_swh_fallback: bool -> t -> t
175
176 (** Return the opam version *)
177 val opam_version: t -> opam_version
178
179 (** Return the opam root version, if not defined returns the default version
180 value [2.1~~previous] *)
181 val opam_root_version: t -> opam_version
182
183 (** Return the opam root version if defined *)
184 val opam_root_version_opt: t -> opam_version option
185
186 (** Return the list of repository *)
187 val repositories: t -> repository_name list
188
189 (** Return the OCaml switch *)
190 val switch: t -> switch option
191
192 val previous_switch : t -> switch option
193
194 val installed_switches: t -> switch list
195
196 (** Return the number of jobs defined *)
197 val jobs: t -> int option
198
199 val dl_tool: t -> arg list option
200
201 (** Return the number of download jobs *)
202 val dl_jobs: t -> int
203
204 val dl_cache: t -> url list
205
206 val criteria: t -> (solver_criteria * string) list
207
208 val best_effort_prefix: t -> string option
209
210 val solver: t -> arg list option
211
212 val wrappers: t -> Wrappers.t
213
214 (** variable, value, docstring *)
215 val global_variables: t -> (variable * variable_contents * string) list
216
217 (** variable, command, docstring *)
218 val eval_variables: t -> (variable * string list * string) list
219
220 val validation_hook: t -> arg list option
221
222 val default_compiler: t -> formula
223 val default_invariant: t -> formula
224
225 val depext: t -> bool
226 val depext_run_installs: t -> bool
227 val depext_cannot_install: t -> bool
228 val depext_bypass: t -> OpamSysPkg.Set.t
229
230 val sys_pkg_manager_cmd: t -> filename OpamStd.String.Map.t
231
232 (* Enable or disable Software Heritage fallback for unreachable package
233 sources *)
234 val swh_fallback: t -> bool
235
236 val fields: (string * (t, value) OpamPp.field_parser) list
237
238 (** All file fields as print-AST, Fields within sections are
239 accessed through dot-separated paths *)
240 val to_list: ?filename:'a typed_file -> t -> (string * value) list
241
242 module BestEffort: BestEffortRead with type t := t
243
244 (** Raw read the config file to extract [opam-root-version] field value. *)
245 val raw_root_version: 'a typed_file -> OpamVersion.t option
246 end
247
248 (** Init config file [/etc/opamrc] *)
249 module InitConfig: sig
250 include IO_FILE
251
252 val opam_version: t -> opam_version
253 val repositories: t -> (repository_name * (url * trust_anchors option)) list
254 val default_compiler: t -> formula
255 val default_invariant: t -> formula
256 val jobs: t -> int option
257 val dl_tool: t -> arg list option
258 val dl_jobs: t -> int option
259 val dl_cache: t -> url list
260 val solver_criteria: t -> (solver_criteria * string) list
261 val solver: t -> arg list option
262 val wrappers: t -> Wrappers.t
263 val global_variables: t -> (variable * variable_contents * string) list
264 val eval_variables: t -> (variable * string list * string) list
265 val recommended_tools: t -> (string list * string option * filter option) list
266 val required_tools: t -> (string list * string option * filter option) list
267 val init_scripts: t -> ((string * string) * filter option) list
268
269 val with_opam_version: opam_version -> t -> t
270 val with_repositories:
271 (repository_name * (url * trust_anchors option)) list -> t -> t
272 val with_default_compiler: formula -> t -> t
273 val with_default_invariant: formula -> t -> t
274 val with_jobs: int option -> t -> t
275 val with_dl_tool: arg list option -> t -> t
276 val with_dl_jobs: int option -> t -> t
277 val with_dl_cache: url list -> t -> t
278 val with_solver_criteria: (solver_criteria * string) list -> t -> t
279 val with_solver: arg list option -> t -> t
280 val with_wrappers: Wrappers.t -> t -> t
281 val with_global_variables: (variable * variable_contents * string) list -> t -> t
282 val with_eval_variables: (variable * string list * string) list -> t -> t
283 val with_recommended_tools: (string list * string option * filter option) list -> t -> t
284 val with_required_tools: (string list * string option * filter option) list -> t -> t
285 val with_init_scripts: ((string * string) * filter option) list -> t -> t
286
287 (** [add t1 t2] is [t2], with the field values falling back to those of [t1]
288 when not set in [t2] *)
289 val add: t -> t -> t
290 end
291
292 (** Package descriptions: [$opam/descr/] *)
293 module Descr: sig
294
295 include IO_FILE
296
297 val create: string -> t
298
299 (** Create an abstract description file from a string *)
300 val of_string: t typed_file -> string -> t
301
302 (** Return the first line *)
303 val synopsis: t -> string
304
305 (** Return the body *)
306 val body: t -> string
307
308 (** Return the full description *)
309 val full: t -> string
310
311 end
312
313 (** {2 Urls for OPAM repositories} *)
314 module URL: sig
315
316 include IO_FILE
317
318 val create:
319 ?mirrors:url list -> ?checksum:OpamHash.t list ->
320 ?swhid:OpamSWHID.t -> ?subpath:subpath ->
321 url -> t
322
323 (** URL address *)
324 val url: t -> url
325
326 val mirrors: t -> url list
327
328 (** Archive checksum *)
329 val checksum: t -> OpamHash.t list
330 val swhid: t -> OpamSWHID.t option
331
332 (** Constructor *)
333 val with_url: url -> t -> t
334 val with_checksum: OpamHash.t list -> t -> t
335 val with_mirrors: OpamUrl.t list -> t -> t
336 val with_swhid: OpamSWHID.t -> t -> t
337 val with_swhid_opt: OpamSWHID.t option -> t -> t
338 val with_subpath: subpath -> t -> t
339 val with_subpath_opt: subpath option -> t -> t
340
341 val subpath: t -> subpath option
342
343 end
344
345 (** OPAM files *)
346 module OPAM: sig
347
348 type t = private {
349 opam_version: opam_version;
350
351 (* Package ident *)
352 name : name option;
353 version : version option;
354
355 (* Relationships; solver and availability info *)
356 depends : filtered_formula;
357 depopts : filtered_formula;
358 conflicts : filtered_formula;
359 conflict_class : name list;
360 available : filter;
361 flags : package_flag list;
362 env : env_update list;
363
364 (* Build instructions *)
365 build : command list;
366 run_test : command list;
367 install : command list;
368 remove : command list;
369
370 (* Auxiliary data affecting the build *)
371 substs : basename list;
372 patches : (basename * filter option) list;
373 build_env : env_update list;
374 features : (OpamVariable.t * filtered_formula * string) list;
375 extra_sources: (basename * URL.t) list;
376
377 (* User-facing data used by opam *)
378 messages : (string * filter option) list;
379 post_messages: (string * filter option) list;
380 depexts : (OpamSysPkg.Set.t * filter) list;
381 libraries : (string * filter option) list;
382 syntax : (string * filter option) list;
383 dev_repo : url option;
384 pin_depends: (package * url) list;
385
386 (* Package database details *)
387 maintainer : string list;
388 author : string list;
389 license : string list;
390 tags : string list;
391 homepage : string list;
392 doc : string list;
393 bug_reports: string list;
394
395 (* Extension fields (x-foo: "bar") *)
396 extensions : value OpamStd.String.Map.t;
397
398 (* Extra sections *)
399 url : URL.t option;
400 descr : Descr.t option;
401
402 (* Related metadata directory (not an actual field of the file)
403 This can be used to locate e.g. the files/ overlays.
404 If the repository is specified, the string is a relative path from its
405 root. It should otherwise be an absolute path. *)
406 metadata_dir: (repository_name option * string) option;
407
408 (* Names and hashes of the files below files/ *)
409 extra_files: (OpamFilename.Base.t * OpamHash.t) list option;
410
411 (* Origin with the extension *)
412 locked: string option;
413
414 format_errors: (string * OpamPp.bad_format) list;
415
416 (* Deprecated, for compat and proper linting *)
417 ocaml_version: (OpamFormula.relop * string) OpamFormula.formula option;
418 os : (bool * string) generic_formula;
419 deprecated_build_test : command list;
420 deprecated_build_doc : command list;
421 }
422
423 include IO_FILE with type t := t
424
425 val empty: t
426
427 (** Create an opam file *)
428 val create: package -> t
429
430 (** Returns the opam value (including url, descr) with all non-effective (i.e.
431 user-directed information that doesn't change opam's view on the package)
432 fields set to their empty values. Useful for comparisons.
433 @param ?modulo_state if [true], eliminates the fields relying on the state
434 of the switch (depends, available, …). This is [false] by default. *)
435 val effective_part: ?modulo_state:bool -> t -> t
436
437 (** Returns true if the effective parts of the two package definitions are
438 equal.
439 @param ?modulo_state if [true], considers the fields relying on the state
440 of the switch (depends, available, …) equal. This is [false] by default *)
441 val effectively_equal: ?modulo_state:bool -> t -> t -> bool
442
443 (** Compares two package definitions, ignoring the virtual fields bound to
444 file location ([metadata_dir]...) *)
445 val equal: t -> t -> bool
446
447 (** Prints the format errors that were found when the file was read *)
448 val print_errors: ?file:t typed_file -> t -> unit
449
450 (** Get OPAM version. *)
451 val opam_version: t -> opam_version
452
453 (** Package name *)
454 val name: t -> name
455 val name_opt: t -> name option
456
457 (** Package version *)
458 val version: t -> version
459 val version_opt: t -> version option
460
461 (** The informations in both the name and version fields, as a package *)
462 val package: t -> package
463
464 (** Availability formula (OS + compiler constraints) *)
465 val available: t -> filter
466
467 (** Package maintainer(s) *)
468 val maintainer: t -> string list
469
470 (** File substitutions *)
471 val substs: t -> basename list
472
473 (** List of environment variables to set-up for the build *)
474 val build_env: t -> env_update list
475
476 (** List of command to run for building the package *)
477 val build: t -> command list
478
479 (** List of command to run for installing the package *)
480 val install: t -> command list
481
482 (** List of command to run for removing the package *)
483 val remove: t -> command list
484
485 (** Package dependencies *)
486 val depends: t -> filtered_formula
487
488 (** Optional dependencies *)
489 val depopts: t -> filtered_formula
490
491 (** External dependencies *)
492 val depexts: t -> (OpamSysPkg.Set.t * filter) list
493
494 val extra_sources: t -> (basename * URL.t) list
495
496 (** All extended "x-" fields as a map *)
497 val extensions: t -> value OpamStd.String.Map.t
498
499 (** Parse a single extended field (reports proper file position) *)
500 val extended: t -> string -> (value -> 'a) -> 'a option
501
502 val with_messages: (string * filter option) list -> t -> t
503
504 val with_post_messages: (string * filter option) list -> t -> t
505
506 (** Package conflicts *)
507 val conflicts: t -> filtered_formula
508
509 val conflict_class: t -> name list
510
511 (** Contents of the 'features' field *)
512 val features: t -> (OpamVariable.t * filtered_formula * string) list
513
514 (** List of exported libraries *)
515 val libraries: t -> (string * filter option) list
516
517 (** List of exported syntax extensions *)
518 val syntax: t -> (string * filter option) list
519
520 (** Patches *)
521 val patches: t -> (basename * filter option) list
522
523 (** Homepage(s) *)
524 val homepage: t -> string list
525
526 (** Author(s) *)
527 val author: t -> string list
528
529 (** License(s) *)
530 val license: t -> string list
531
532 (** API documentation *)
533 val doc: t -> string list
534
535 (** Classification tags *)
536 val tags: t -> string list
537
538 (** Commands to build and run the tests *)
539 val run_test: t -> command list
540
541 (** Commands to build the documentation *)
542 val deprecated_build_doc: t -> command list
543
544 (** Commands to build the tests *)
545 val deprecated_build_test: t -> command list
546
547 (** Messages to display before taking action *)
548 val messages: t -> (string * filter option) list
549
550 (** Messages to display at end of install *)
551 val post_messages: t -> (string * filter option) list
552
553 (** Where to post bug reports. *)
554 val bug_reports: t -> string list
555
556 (** The package flags that are present for this package. *)
557 val flags: t -> package_flag list
558
559 (** Check the package for the given flag. Allows flags specified through tags
560 for compatibility *)
561 val has_flag: package_flag -> t -> bool
562
563 (** The environment variables that this package exports *)
564 val env: t -> env_update list
565
566 val descr: t -> Descr.t option
567
568 val synopsis: t -> string option
569 val descr_body: t -> string option
570
571 val url: t -> URL.t option
572
573 val get_url: t -> url option
574
575 (** Related metadata directory (either repository name + relative path, or
576 absolute path; not an actual field of the file, linked to the file
577 location).
578 This can be used to locate e.g. the files/ overlays *)
579 val metadata_dir: t -> (repository_name option * string) option
580
581 (** Gets the resolved metadata dir, given a mapping of repository names to
582 their roots *)
583 val get_metadata_dir:
584 repos_roots:(repository_name -> dirname) -> t -> dirname option
585
586 (** Names and hashes of the files below files/ *)
587 val extra_files: t -> (OpamFilename.Base.t * OpamHash.t) list option
588
589 (** From locked opam file *)
590 val locked: t -> string option
591
592 (** Looks up the extra files, and returns their full paths, relative path to
593 the package source, and hash. Doesn't check the hashes. *)
594 val get_extra_files:
595 repos_roots:(repository_name -> dirname) ->
596 t -> (filename * basename * OpamHash.t) list
597
598 (** Returns the errors that were found when parsing the file, associated to
599 their fields (that were consequently ignored) *)
600 val format_errors: t -> (string * OpamPp.bad_format) list
601
602 (** Sets the opam version *)
603 val with_opam_version: opam_version -> t -> t
604
605 (** The package source repository address *)
606 val dev_repo: t -> url option
607
608 val pin_depends: t -> (package * url) list
609
610 (** construct as [name] *)
611 val with_name: name -> t -> t
612 val with_name_opt: name option -> t -> t
613
614 (** construct as [version] *)
615 val with_version: version -> t -> t
616 val with_version_opt: version option -> t -> t
617
618 (** Construct as [depends] *)
619 val with_depends: filtered_formula -> t -> t
620
621 (** Construct as [depopts] *)
622 val with_depopts: filtered_formula -> t -> t
623
624 val with_conflicts: filtered_formula -> t -> t
625
626 val with_conflict_class: name list -> t -> t
627
628 val with_features: (OpamVariable.t * filtered_formula * string) list -> t -> t
629
630 (** Construct as [build] *)
631 val with_build: command list -> t -> t
632
633 val with_run_test: command list -> t -> t
634
635 val with_install: command list -> t -> t
636
637 (** Construct as [remove] *)
638 val with_remove: command list -> t -> t
639
640 (** Construct as [libraries] *)
641 val with_libraries: (string * filter option) list -> t -> t
642
643 (** Replace the [syntax] field of the given OPAM file. *)
644 val with_syntax: (string * filter option) list -> t -> t
645
646 (** Construct as [substs] *)
647 val with_substs: basename list -> t -> t
648
649 val with_build_env: env_update list -> t -> t
650
651 val with_available: filter -> t -> t
652
653 (** Construct as [maintainer] *)
654 val with_maintainer: string list -> t -> t
655
656 val with_author: string list -> t -> t
657
658 val with_homepage: string list -> t -> t
659
660 val with_license: string list -> t -> t
661
662 (** Construct as [patches] *)
663 val with_patches: (basename * filter option) list -> t -> t
664
665 (** Construct using [bug_reports] *)
666 val with_bug_reports: string list -> t -> t
667
668 (** Construct using [depexts] *)
669 val with_depexts: (OpamSysPkg.Set.t * filter) list -> t -> t
670
671 val with_flags: package_flag list -> t -> t
672
673 val add_flags: package_flag list -> t -> t
674
675 val with_tags: string list -> t -> t
676
677 val with_env: env_update list -> t -> t
678
679 val with_dev_repo: url -> t -> t
680
681 val with_dev_repo_opt: url option -> t -> t
682
683 val with_pin_depends: (package * url) list -> t -> t
684
685 val with_extra_sources: (basename * URL.t) list -> t -> t
686
687 val with_extensions: value OpamStd.String.Map.t -> t -> t
688
689 val add_extension: t -> string -> value -> t
690
691 val remove_extension: t -> string -> t
692
693 val with_deprecated_build_doc: command list -> t -> t
694
695 val with_deprecated_build_test: command list -> t -> t
696
697 val with_descr: Descr.t -> t -> t
698 val with_descr_opt: Descr.t option -> t -> t
699 val with_synopsis: string -> t -> t
700
701 (** If [synopsis] is not already set, split the string and use the first line
702 as synopsis. *)
703 val with_descr_body: string -> t -> t
704
705 val with_url: URL.t -> t -> t
706 val with_url_opt: URL.t option -> t -> t
707
708 val with_metadata_dir: (repository_name option * string) option -> t -> t
709
710 val with_extra_files: (OpamFilename.Base.t * OpamHash.t) list -> t -> t
711 val with_extra_files_opt: (OpamFilename.Base.t * OpamHash.t) list option -> t -> t
712
713 val with_locked_opt: string option -> t -> t
714
715 val with_format_errors: (string * OpamPp.bad_format) list -> t -> t
716
717 (** Prints to a string, while keeping the format of the original file as much
718 as possible. The original format is read from the given
719 [format_from_string], the file [format_from], or the output file if
720 it exists *)
721 val to_string_with_preserved_format:
722 ?format_from:(t typed_file) -> ?format_from_string:string ->
723 t typed_file -> t -> string
724
725 (** Writes an opam file, but preserving the existing formatting as much as
726 possible. The original format is read from the given
727 [format_from_string], the file [format_from], or the output file if
728 it exists *)
729 val write_with_preserved_format:
730 ?format_from:(t typed_file) -> ?format_from_string:string ->
731 t typed_file -> t -> unit
732
733 (** Low-level values used for linting and similar processing *)
734
735 (** Allow 'flag:xxx' tags as flags, for compat *)
736 val flag_of_tag: string -> package_flag option
737
738 val fields: (t, value) OpamFormat.I.fields_def
739
740 val sections:
741 (t, (string option * opamfile_item list) list) OpamFormat.I.fields_def
742
743 (** Doesn't handle package name encoded in directory name *)
744 val pp_raw_fields: (opamfile_item list, t) OpamPp.t
745
746 (** Returns the raw print-AST contents of the file *)
747 val contents: ?filename:'a typed_file -> t -> opamfile
748
749 (** Returns all fields of the file as print-AST. Fields within sections are
750 accessed through dot-separated paths (e.g. [url.checksum]) *)
751 val to_list: ?filename:'a typed_file -> t -> (string * value) list
752
753 (** Gets the print-AST for a single field in the file structure. Fields within
754 sections can be accessed through [section.field]. *)
755 val print_field_as_syntax: string -> t -> value option
756
757 end
758
759 (** Compiler aliases: [$opam/aliases]. Deprecated, used only for migration *)
760 module Aliases: IO_FILE with type t = string switch_map
761
762 (** Switch state file as table, also used for import/export. This includes
763 compiler and root packages information, as well as pinned packages and their
764 target (but not their local metadata). *)
765 module LegacyState: sig
766 type t = switch_selections
767 include IO_FILE with type t := t
768 end
769
770 (** A newer format for switch state, using the opam file syntax rather than a
771 table. This is more readable and extensible. *)
772 module SwitchSelections: sig
773 type t = switch_selections
774 include IO_FILE with type t := t
775 module BestEffort: BestEffortRead with type t := t
776 end
777
778 (** An extended version of SwitchSelections that can include full opam files as
779 [package "name" {}] sections, for storing overlays *)
780 module SwitchExport: sig
781 type t = {
782 selections: switch_selections;
783 extra_files: string OpamHash.Map.t;
784 overlays: OPAM.t OpamPackage.Name.Map.t;
785 }
786 include IO_FILE with type t := t
787 end
788
789 (** A simple list of packages and versions: (used for the older
790 [$opam/$switch/{installed,installed_roots}], still needed to
791 migrate from 1.2 repository, and for reinstall) *)
792 module PkgList: IO_FILE with type t = package_set
793
794 (** Cached environment updates (<switch>/environment) *)
795 module Environment: IO_FILE with type t = env_update list
796
797 (** Compiler version [$opam/compilers/]. Deprecated, only used to upgrade old
798 data *)
799 module Comp: sig
800
801 include IO_FILE
802
803 type compiler = string
804 type compiler_version = string
805
806 (** Create a pre-installed compiler description file *)
807 val create_preinstalled:
808 compiler -> compiler_version -> name list -> env_update list -> t
809
810 (** Is it a pre-installed compiler description file *)
811 val preinstalled: t -> bool
812
813 (** Get OPAM version *)
814 val opam_version: t -> opam_version
815
816 (** Return the compiler name *)
817 val name: t -> compiler
818
819 (** Return the compiler version *)
820 val version: t -> compiler_version
821
822 (** Return the url of the compiler *)
823 val src: t -> url option
824
825 (** Return the list of patches to apply *)
826 val patches: t -> url list
827
828 (** Options to give to the "./configure" command *)
829 val configure: t -> string list
830
831 (** Options to give to the "make" command *)
832 val make: t -> string list
833
834 (** Options to give to build the package. If this one is provided,
835 nothing should be specified for [configure] and [make]. *)
836 val build: t -> command list
837
838 (** Packages to install immediately after the creation of OCaml *)
839 val packages: t -> formula
840
841 (** Environment variable to set-up before running commands in the
842 subtree *)
843 val env: t -> env_update list
844
845 val tags: t -> string list
846
847 val with_src: url option -> t -> t
848 val with_patches: url list -> t -> t
849 val with_configure: string list -> t -> t
850 val with_make: string list -> t -> t
851 val with_build: command list -> t -> t
852 val with_packages: formula -> t -> t
853
854 (** Converts a compiler definition to package metadata. For compat. If
855 [package] is unspecified, a package named "ocaml" is created for
856 "standard" compilers (when the compiler name doesn't contain a "+" and is
857 equal to the compiler version); otherwise, a package "ocaml-VARIANT" is
858 created with "VARIANT" the part of the compiler name on the right of the
859 "+". In both case, the version corresponds to the OCaml version and is
860 [version comp]. *)
861 val to_package: ?package:package -> t -> Descr.t option -> OPAM.t
862
863 end
864
865 (** {2 Configuration files} *)
866
867 (** .install files *)
868 module Dot_install: sig
869
870 include IO_FILE
871
872 (** List of files to install in $bin/ *)
873 val bin: t -> (basename optional * basename option) list
874
875 (** List of files to install in $sbin/ *)
876 val sbin: t -> (basename optional * basename option) list
877
878 (** List of files to install in $lib/ *)
879 val lib: t -> (basename optional * basename option) list
880
881 (** List of toplevel files *)
882 val toplevel: t -> (basename optional * basename option) list
883
884 (** C bindings *)
885 val stublibs: t -> (basename optional * basename option) list
886
887 (** List of architecture-independent files *)
888 val share: t -> (basename optional * basename option) list
889
890 (** List of files under the more general share prefix *)
891 val share_root: t -> (basename optional * basename option) list
892
893 (** List of etc files *)
894 val etc: t -> (basename optional * basename option) list
895
896 (** List of doc files *)
897 val doc: t -> (basename optional * basename option) list
898
899 (** Man pages *)
900 val man: t -> (basename optional * basename option) list
901
902 (** Executable files under lib/ *)
903 val libexec: t -> (basename optional * basename option) list
904
905 (** Not relative to the package's lib dir *)
906 val lib_root: t -> (basename optional * basename option) list
907
908 (** Not relative to the package's lib dir, and with +x set *)
909 val libexec_root: t -> (basename optional * basename option) list
910
911 (** List of other files to install *)
912 val misc: t -> (basename optional * filename) list
913
914 (** List of files to install in $bin/ *)
915 val with_bin : (basename optional * basename option) list -> t -> t
916
917 (** List of files to install in $sbin/ *)
918 val with_sbin : (basename optional * basename option) list -> t -> t
919
920 (** List of files to install in $lib/ *)
921 val with_lib : (basename optional * basename option) list -> t -> t
922
923 (** List of toplevel files *)
924 val with_toplevel : (basename optional * basename option) list -> t -> t
925
926 (** C bindings *)
927 val with_stublibs : (basename optional * basename option) list -> t -> t
928
929 (** List of architecture-independent files *)
930 val with_share : (basename optional * basename option) list -> t -> t
931
932 (** List of files under the more general share prefix *)
933 val with_share_root : (basename optional * basename option) list -> t -> t
934
935 (** List of etc files *)
936 val with_etc : (basename optional * basename option) list -> t -> t
937
938 (** List of doc files *)
939 val with_doc : (basename optional * basename option) list -> t -> t
940
941 (** Man pages *)
942 val with_man : (basename optional * basename option) list -> t -> t
943
944 (** Executable files under lib/ *)
945 val with_libexec : (basename optional * basename option) list -> t -> t
946
947 (** Not relative to the package's lib dir *)
948 val with_lib_root : (basename optional * basename option) list -> t -> t
949
950 (** Not relative to the package's lib dir, and with +x set *)
951 val with_libexec_root : (basename optional * basename option) list -> t -> t
952
953 (** List of other files to install *)
954 val with_misc : (basename optional * filename) list -> t -> t
955
956 end
957
958 (** .changes files, bound to the OpamDirTrack module *)
959 module Changes: sig
960 type t = OpamDirTrack.t
961 include IO_FILE with type t := t
962 end
963
964 (** .config files *)
965 module Dot_config: sig
966
967 include IO_FILE
968
969 (** Create a new .config file (containing only variables) *)
970 val create: (variable * variable_contents) list -> t
971
972 (** Dependency towards file-system paths and their hashes *)
973 val file_depends: t -> (filename * OpamHash.t) list
974
975 val with_file_depends: (filename * OpamHash.t) list -> t -> t
976
977 (** Sets all bindings in the file *)
978 val with_vars: (variable * variable_contents) list -> t -> t
979
980 (** Top-level variables *)
981 val variable: t -> variable -> variable_contents option
982
983 (** The list of top-level variables *)
984 val variables: t -> variable list
985
986 (** Lists all the variable bindings in the file *)
987 val bindings: t -> (variable * variable_contents) list
988
989 (** Sets the given variable, overriding any previous definition.
990 With [None], unsets the variable*)
991 val set: variable -> variable_contents option -> t -> t
992
993 end
994
995 (** {2 Repository files} *)
996
997 (** Association between package names and repositories *)
998 module Package_index: IO_FILE with
999 type t = (repository_name * string option) package_map
1000
1001 (** Repository config: [$opam/repo/$repo/config]. Deprecated, for migration
1002 only *)
1003 module Repo_config_legacy : sig
1004 type t = {
1005 repo_name : repository_name;
1006 repo_root : dirname;
1007 repo_url : url;
1008 repo_priority : int;
1009 }
1010 include IO_FILE with type t := t
1011 end
1012
1013 module Repos_config: sig
1014 type t = (url * trust_anchors option) option OpamRepositoryName.Map.t
1015 include IO_FILE with type t := t
1016 module BestEffort: BestEffortRead with type t := t
1017 end
1018
1019 module Switch_config: sig
1020 type t = {
1021 opam_version: OpamVersion.t;
1022 synopsis: string;
1023 repos: repository_name list option;
1024 paths: (std_path * string) list;
1025 variables: (variable * variable_contents) list;
1026 opam_root: dirname option;
1027 wrappers: Wrappers.t;
1028 env: env_update list;
1029 invariant: OpamFormula.t option;
1030 depext_bypass: OpamSysPkg.Set.t;
1031 }
1032 val file_format_version: OpamVersion.t
1033 val variable: t -> variable -> variable_contents option
1034 val path: t -> std_path -> string option
1035 val wrappers: t -> Wrappers.t
1036 val sections: (string * (t, (string option * opamfile_item list) list) OpamPp.field_parser) list
1037 val fields: (string * (t, value) OpamPp.field_parser) list
1038 val to_list: ?filename:'a typed_file -> t -> (string * value) list
1039 include IO_FILE with type t := t
1040 val oldest_compatible_format_version: OpamVersion.t
1041
1042 module BestEffort: BestEffortRead with type t := t
1043 end
1044
1045 (** Pinned package files (only used for migration from 1.2, the inclusive State
1046 module is now used instead) *)
1047 module Pinned_legacy: sig
1048 type pin_option =
1049 | Version of version
1050 | Source of url
1051 include IO_FILE with type t = pin_option name_map
1052 end
1053
1054 (** Repository metadata *)
1055 module Repo: sig
1056
1057 include IO_FILE
1058
1059 val create:
1060 ?browse:string -> ?upstream:string -> ?opam_version:OpamVersion.t ->
1061 ?redirect:(string * filter option) list -> ?root_url:url ->
1062 ?dl_cache:string list -> ?announce:(string * filter option) list ->
1063 ?stamp:string ->
1064 unit -> t
1065
1066 (** The minimum OPAM version required for this repository, if defined *)
1067 val opam_version : t -> OpamVersion.t option
1068
1069 (** Base URL for browsing packages on the WWW *)
1070 val browse: t -> string option
1071
1072 (** Base URL for browsing OPAM repository source on the WWW *)
1073 val upstream: t -> string option
1074
1075 (** The root URL of the repository (not an actual file field, determined at
1076 runtime by opam) *)
1077 val root_url: t -> url option
1078
1079 (** Redirections. *)
1080 val redirect: t -> (string * filter option) list
1081
1082 (** Cache URLs, either full or relative to the repo root *)
1083 val dl_cache: t -> string list
1084
1085 val announce: t -> (string * filter option) list
1086
1087 val stamp: t -> string option
1088
1089 val with_opam_version : OpamVersion.t -> t -> t
1090
1091 val with_browse: string -> t -> t
1092
1093 val with_upstream: string -> t -> t
1094
1095 val with_redirect: (string * filter option) list -> t -> t
1096
1097 val with_root_url: url -> t -> t
1098
1099 val with_dl_cache: string list -> t -> t
1100
1101 val with_announce: (string * filter option) list -> t -> t
1102
1103 val with_stamp: string -> t -> t
1104
1105 val with_stamp_opt: string option -> t -> t
1106 end
1107
1108 (** {2 urls.txt file *} *)
1109 module File_attributes: IO_FILE with type t = file_attribute_set
1110
1111 module Stats: sig
1112
1113 (** Display statistics about file access. *)
1114 val print: unit -> unit
1115
1116 end
1117
1118 (** Helper module for manipulation of the raw syntax ([opamfile]) format.
1119 (the specific file handling modules are derived from this one) *)
1120 module Syntax : sig
1121
1122 val pp_channel:
1123 'a typed_file -> in_channel -> out_channel ->
1124 (unit, opamfile) OpamPp.t
1125
1126 val of_channel: 'a typed_file -> in_channel -> opamfile
1127 val to_channel: 'a typed_file -> out_channel -> opamfile -> unit
1128 val of_string: 'a typed_file -> string -> opamfile
1129 val to_string: 'a typed_file -> opamfile -> string
1130 val to_string_with_preserved_format:
1131 'a typed_file -> ?format_from:'a typed_file -> ?format_from_string:string ->
1132 empty:'a ->
1133 ?sections:('a, (string option * opamfile_item list) list)
1134 OpamFormat.I.fields_def ->
1135 fields:('a, value) OpamFormat.I.fields_def ->
1136 (opamfile, filename * 'a) OpamPp.t ->
1137 'a -> string
1138
1139 end
1140
1141 (**/**)
1142
1143 module type SyntaxFileArg = sig
1144 val internal: string
1145 val atomic: bool
1146 val format_version: OpamVersion.t
1147 type t
1148 val empty: t
1149 val pp: (opamfile, filename * t) OpamPp.t
1150 end
1151
1152 module SyntaxFile(X: SyntaxFileArg) : IO_FILE with type t := X.t
1153
1154 module type LineFileArg = sig
1155 val internal: string
1156 val atomic: bool
1157 type t
1158 val empty: t
1159 val pp: (string list list, t) OpamPp.t
1160 end
1161
1162 module LineFile (X: LineFileArg) : IO_FILE with type t := X.t