erlang: rip out edoc

Summary:
OTP 27 introduces the new `-moduledoc` and `-doc` mechanism integrated into the compiler.

This removes support from buck2 for the legacy edoc mechanism, that required forking parts of OTP and a lot of workarounds to get it working properly.

Reviewed By: TD5, TheGeorge

Differential Revision: D74240702

fbshipit-source-id: 3d2df545f2e397879ab6f71dd457842b52fb1222

Author: michalmuskala

prelude/decls/erlang_rules.bzl

@@ -88,9 +88,6 @@ rules_attributes = {
                 or `included_applications` buck2 checks that the target definitions and information in the template are equivalent to
                 prevent these definitions from drifting apart during migration._
             """),
-        "build_edoc_chunks": attrs.bool(default = False, doc = """
-                This attribute controls if the output of the builds also create edoc chunks.
-            """),
         "env": attrs.option(attrs.dict(key = attrs.string(), value = attrs.string()), default = None, doc = """
                 The `env` field allows to set the application env variables. The key value pairs will materialise in the application's `.app`
                 file and can then be accessed by [`application:get_env/2`](https://www.erlang.org/doc/man/application.html#get_env-2).

prelude/erlang/erlang_application.bzl

@@ -186,15 +186,6 @@ def _build_erlang_application(ctx: AnalysisContext, toolchain: Toolchain, depend
         src_artifacts,
     )
 
-    # edoc chunks (only materialised in edoc subtarget)
-    build_environment = erlang_build.build_steps.generate_chunk_artifacts(
-        ctx,
-        toolchain,
-        build_environment,
-        name,
-        src_artifacts,
-    )
-
     # create <appname>.app file
     build_environment = _generate_app_file(
         ctx,
@@ -337,7 +328,6 @@ def link_output(
 
     ebin = build_environment.app_beams.values() + [build_environment.app_files[name]]
     include = build_environment.include_dirs[name]
-    chunks = build_environment.app_chunks.values()
     priv = build_environment.priv_dirs[name]
 
     ebin = {
@@ -347,18 +337,9 @@ def link_output(
 
     srcs = _link_srcs_folder(ctx)
 
-    if getattr(ctx.attrs, "build_edoc_chunks", False):
-        edoc = {
-            paths.join("doc", "chunks", chunk_file.basename): chunk_file
-            for chunk_file in chunks
-        }
-    else:
-        edoc = {}
-
     link_spec = {}
     link_spec.update(ebin)
     link_spec.update(srcs)
-    link_spec.update(edoc)
     link_spec["include"] = include
     link_spec["priv"] = priv
 

prelude/erlang/erlang_build.bzl

@@ -51,7 +51,6 @@ BuildEnvironment = record(
     # convenience storrage
     app_includes = field(IncludesMapping, {}),
     app_beams = field(ModuleArtifactMapping, {}),
-    app_chunks = field(ModuleArtifactMapping, {}),
     # input artifact mapping
     input_mapping = field(InputArtifactMapping, {}),
 )
@@ -61,11 +60,6 @@ DepInfo = record(
     path = field(str),
 )
 
-Anchor = record(
-    artifact = field(Artifact),
-    dirname = field(str),
-)
-
 def _prepare_build_environment(
         ctx: AnalysisContext,
         toolchain: Toolchain,
@@ -175,7 +169,6 @@ def _generate_input_mapping(build_environment: BuildEnvironment, input_artifacts
         app_files = build_environment.app_files,
         app_includes = build_environment.app_includes,
         app_beams = build_environment.app_beams,
-        app_chunks = build_environment.app_chunks,
     )
 
 def _generated_source_artifacts(ctx: AnalysisContext, toolchain: Toolchain, name: str) -> PathArtifactMapping:
@@ -288,51 +281,6 @@ def _generate_beam_artifacts(
 
     return updated_build_environment
 
-def _generate_chunk_artifacts(
-        ctx: AnalysisContext,
-        toolchain: Toolchain,
-        build_environment: BuildEnvironment,
-        name: str,
-        src_artifacts: list[Artifact]) -> BuildEnvironment:
-    anchor = _make_dir_anchor(ctx, paths.join(_build_dir(toolchain), name, "chunks"))
-
-    chunk_mapping = {
-        module_name(src): ctx.actions.declare_output(chunk_path(anchor, src))
-        for src in src_artifacts
-    }
-
-    updated_build_environment = BuildEnvironment(
-        app_chunks = chunk_mapping,
-        # copied fields
-        includes = build_environment.includes,
-        private_includes = build_environment.private_includes,
-        beams = build_environment.beams,
-        priv_dirs = build_environment.priv_dirs,
-        include_dirs = build_environment.include_dirs,
-        private_include_dir = build_environment.private_include_dir,
-        deps_files = build_environment.deps_files,
-        app_files = build_environment.app_files,
-        app_includes = build_environment.app_includes,
-        app_beams = build_environment.app_beams,
-        input_mapping = build_environment.input_mapping,
-    )
-
-    preprocess_modules = toolchain.edoc_preprocess
-    preprocess_all = "__all__" in preprocess_modules
-
-    for erl in src_artifacts:
-        preprocess = preprocess_all or module_name(erl) in preprocess_modules
-        _build_edoc(ctx, toolchain, updated_build_environment, erl, chunk_mapping[module_name(erl)], preprocess)
-
-    return updated_build_environment
-
-def _make_dir_anchor(ctx: AnalysisContext, path: str) -> Anchor:
-    artifact = ctx.actions.write(
-        paths.normalize(paths.join(path, ".hidden")),
-        cmd_args([""]),
-    )
-    return Anchor(dirname = paths.dirname(artifact.short_path), artifact = artifact)
-
 def _get_deps_files(
         ctx: AnalysisContext,
         toolchain: Toolchain,
@@ -449,48 +397,6 @@ def _build_erl(
     ctx.actions.dynamic_output(dynamic = [final_dep_file], inputs = [src], outputs = [output.as_output()], f = dynamic_lambda)
     return None
 
-def _build_edoc(
-        ctx: AnalysisContext,
-        toolchain: Toolchain,
-        build_environment: BuildEnvironment,
-        src: Artifact,
-        output: Artifact,
-        preprocess: bool) -> None:
-    """Build edoc from erl files."""
-    eval_cmd = cmd_args(
-        toolchain.otp_binaries.escript,
-        toolchain.edoc,
-        cmd_args(toolchain.edoc_options),
-        "-app",
-        ctx.attrs.name,
-        "-files",
-        src,
-        "-chunks",
-        "-pa",
-        toolchain.utility_modules,
-        "-o",
-        cmd_args(output.as_output(), parent = 2),
-    )
-
-    if not preprocess:
-        eval_cmd.add("-no-preprocess")
-
-    private_include = build_environment.private_include_dir
-    public_includes = build_environment.include_dirs.values()
-    eval_cmd.add(cmd_args(private_include, prepend = "-I"))
-    eval_cmd.add(cmd_args(public_includes, prepend = "-I"))
-    eval_cmd.add(cmd_args(public_includes, prepend = "-I", parent = 2))
-
-    _run_with_env(
-        ctx,
-        toolchain,
-        eval_cmd,
-        always_print_stderr = True,
-        category = "edoc",
-        identifier = action_identifier(toolchain, src.basename),
-    )
-    return None
-
 def _dependencies_to_args(
         artifacts,
         final_dep_file: Artifact,
@@ -636,18 +542,6 @@ def generated_erl_path(toolchain: Toolchain, appname: str, src: Artifact) -> str
         "%s.erl" % (module_name(src),),
     )
 
-def anchor_path(anchor: Anchor, basename: str) -> str:
-    """ Returns the output path for hrl files. """
-    return paths.join(anchor.dirname, basename)
-
-def beam_path(anchor: Anchor, src: Artifact) -> str:
-    """ Returns the output path for beam files. """
-    return anchor_path(anchor, module_name(src) + ".beam")
-
-def chunk_path(anchor: Anchor, src: Artifact) -> str:
-    """Returns the output path for chunk files."""
-    return anchor_path(anchor, module_name(src) + ".chunk")
-
 def module_name(in_file: Artifact) -> str:
     """ Returns the basename of the artifact without extension """
     end = in_file.basename.rfind(".")
@@ -760,18 +654,20 @@ default_escript_args = cmd_args(
     "minimal",
     "-noinput",
     "-noshell",
+    "-run",
+    "escript",
+    "start",
 )
 
 def _run_escript(ctx: AnalysisContext, toolchain: Toolchain, script: Artifact, args: cmd_args, **kwargs) -> None:
     """ run escript with env and providing toolchain-configured utility modules"""
     cmd = cmd_args(
         toolchain.otp_binaries.erl,
         default_escript_args,
-        "-pa",
-        toolchain.utility_modules,
-        "-run",
-        "escript",
-        "start",
+    )
+    if toolchain.utility_modules:
+        cmd.add("-pa", toolchain.utility_modules)
+    cmd.add(
         "--",
         script,
         args,
@@ -809,7 +705,6 @@ def _peek_private_includes(
         app_files = build_environment.app_files,
         app_includes = build_environment.app_includes,
         app_beams = build_environment.app_beams,
-        app_chunks = build_environment.app_chunks,
         input_mapping = build_environment.input_mapping,
     )
 
@@ -822,7 +717,6 @@ erlang_build = struct(
         generated_source_artifacts = _generated_source_artifacts,
         generate_include_artifacts = _generate_include_artifacts,
         generate_beam_artifacts = _generate_beam_artifacts,
-        generate_chunk_artifacts = _generate_chunk_artifacts,
     ),
     utils = struct(
         is_hrl = _is_hrl,
@@ -832,7 +726,6 @@ erlang_build = struct(
         is_config = _is_config,
         module_name = module_name,
         private_include_name = private_include_name,
-        make_dir_anchor = _make_dir_anchor,
         build_dir = _build_dir,
         run_with_env = _run_with_env,
         run_escript = _run_escript,

prelude/erlang/erlang_info.bzl

@@ -106,10 +106,6 @@ ErlangToolchainInfo = provider(
         "release_variables_builder": provider_field(typing.Any, default = None),
         # copying erts
         "include_erts": provider_field(typing.Any, default = None),
-        # edoc-generating escript
-        "edoc": provider_field(typing.Any, default = None),
-        "edoc_options": provider_field(typing.Any, default = None),
-        "edoc_preprocess": provider_field(list[str], default = []),
         # beams we need for various reasons
         "utility_modules": provider_field(typing.Any, default = None),
         # env to be set for toolchain invocations

prelude/erlang/erlang_tests.bzl

@@ -160,7 +160,6 @@ def erlang_test_impl(ctx: AnalysisContext) -> list[Provider]:
         # convenience storrage
         app_includes = pre_build_environment.app_includes,
         app_beams = pre_build_environment.app_beams,
-        app_chunks = pre_build_environment.app_chunks,
         # input mapping
         input_mapping = pre_build_environment.input_mapping,
     )

prelude/erlang/erlang_toolchain.bzl

@@ -49,9 +49,6 @@ Toolchain = record(
     core_parse_transforms = field(dict[str, (Artifact, Artifact)]),
     parse_transforms = field(dict[str, (Artifact, Artifact)]),
     parse_transforms_filters = field(dict[str, list[str]]),
-    edoc = field(Artifact),
-    edoc_options = field(list[str]),
-    edoc_preprocess = field(list[str]),
     utility_modules = field(Artifact),
     env = field(dict[str, str]),
 )
@@ -64,7 +61,6 @@ ToolchainUtillInfo = provider(
         "core_parse_transforms": provider_field(typing.Any, default = None),
         "dependency_analyzer": provider_field(typing.Any, default = None),
         "dependency_finalizer": provider_field(typing.Any, default = None),
-        "edoc": provider_field(typing.Any, default = None),
         "erlc_trampoline": provider_field(typing.Any, default = None),
         "escript_trampoline": provider_field(typing.Any, default = None),
         "escript_builder": provider_field(typing.Any, default = None),
@@ -107,9 +103,6 @@ def _multi_version_toolchain_impl(ctx: AnalysisContext) -> list[Provider]:
             core_parse_transforms = toolchain_info.core_parse_transforms,
             parse_transforms = toolchain_info.parse_transforms,
             parse_transforms_filters = toolchain_info.parse_transforms_filters,
-            edoc = toolchain_info.edoc,
-            edoc_options = toolchain_info.edoc_options,
-            edoc_preprocess = toolchain_info.edoc_preprocess,
             utility_modules = toolchain_info.utility_modules,
             env = toolchain_info.env,
         )
@@ -136,8 +129,6 @@ def _config_erlang_toolchain_impl(ctx: AnalysisContext) -> list[Provider]:
     # split the options string to get a list of options
     erl_opts = ctx.attrs.erl_opts.split()
     emu_flags = ctx.attrs.emu_flags.split()
-    edoc_options = ctx.attrs.edoc_options.split()
-    edoc_preprocess = ctx.attrs.edoc_preprocess.split()
 
     # get otp binaries
     binaries_info = ctx.attrs.otp_binaries[ErlangOTPBinariesInfo]
@@ -197,9 +188,6 @@ def _config_erlang_toolchain_impl(ctx: AnalysisContext) -> list[Provider]:
             core_parse_transforms = core_parse_transforms,
             parse_transforms = parse_transforms,
             parse_transforms_filters = ctx.attrs.parse_transforms_filters,
-            edoc = utils.edoc,
-            edoc_options = edoc_options,
-            edoc_preprocess = edoc_preprocess,
             utility_modules = utility_modules,
         ),
     ]
@@ -279,8 +267,6 @@ config_erlang_toolchain_rule = rule(
     impl = _config_erlang_toolchain_impl,
     attrs = {
         "core_parse_transforms": attrs.list(attrs.dep(), default = ["@prelude//erlang/toolchain:transform_project_root"]),
-        "edoc_options": attrs.string(default = ""),
-        "edoc_preprocess": attrs.string(default = ""),
         "emu_flags": attrs.string(default = ""),
         "env": attrs.dict(key = attrs.string(), value = attrs.string(), default = {}),
         "erl_opts": attrs.string(default = ""),
@@ -359,7 +345,6 @@ def _toolchain_utils(ctx: AnalysisContext) -> list[Provider]:
             core_parse_transforms = ctx.attrs.core_parse_transforms,
             dependency_analyzer = ctx.attrs.dependency_analyzer,
             dependency_finalizer = ctx.attrs.dependency_finalizer,
-            edoc = ctx.attrs.edoc,
             erlc_trampoline = ctx.attrs.erlc_trampoline,
             escript_trampoline = ctx.attrs.escript_trampoline,
             escript_builder = ctx.attrs.escript_builder,
@@ -377,7 +362,6 @@ toolchain_utilities = rule(
         "core_parse_transforms": attrs.list(attrs.dep()),
         "dependency_analyzer": attrs.source(),
         "dependency_finalizer": attrs.source(),
-        "edoc": attrs.source(),
         "erlc_trampoline": attrs.source(),
         "escript_builder": attrs.source(),
         "escript_trampoline": attrs.source(),

prelude/erlang/toolchain/BUCK

@@ -29,15 +29,12 @@ toolchain_utilities(
     core_parse_transforms = [":transform_project_root"],
     dependency_analyzer = "dependency_analyzer.escript",
     dependency_finalizer = "dependency_finalizer.escript",
-    edoc = "edoc_cli.escript",
     erlc_trampoline = "erlc_trampoline.sh",
     escript_builder = "escript_builder.escript",
     escript_trampoline = "escript_trampoline.sh",
     include_erts = "include_erts.escript",
     release_variables_builder = "release_variables_builder.escript",
     utility_modules = [
-        "edoc_doclet_chunks.erl",
-        "edoc_report.erl",
     ],
     visibility = ["PUBLIC"],
 )