dotnet_rules.bzl

# Copyright (c) Meta Platforms, Inc. and affiliates.
#
# This source code is dual-licensed under either the MIT license found in the
# LICENSE-MIT file in the root directory of this source tree or the Apache
# License, Version 2.0 found in the LICENSE-APACHE file in the root directory
# of this source tree. You may select, at your option, one of the
# above-listed licenses.

# TODO(cjhopman): This was generated by scripts/hacks/rules_shim_with_docs.py,
# but should be manually edited going forward. There may be some errors in
# the generated docs, and so those should be verified to be accurate and
# well-formatted (and then delete this TODO)

load(":common.bzl", "buck", "prelude_rule")
load(":dotnet_common.bzl", "FrameworkVersion")
load("@prelude//csharp:csharp_providers.bzl", "DotNetLibraryInfo")

_CSHARP_LIBRARY_OR_EXE_ATTRIBUTES = {
    "srcs": attrs.list(attrs.source(), default = [], doc = """
              The set of C# source files to be compiled, and assembled by this rule.
              Each element may be either a literal string (representing the path within this package), or a target.
          """),
    "framework_ver": attrs.enum(FrameworkVersion, doc = """
              The version of the .Net framework that this library targets. This is
              one of """ + ", ".join(FrameworkVersion) + """.
          """),
    "deps": attrs.list(attrs.one_of(attrs.dep(providers = [DotNetLibraryInfo]), attrs.string()), default = [], doc = """
              The set of targets or system-provided assemblies this target depends on. Any
              values that are targets must be either csharp\\_library or `prebuilt_dotnet_library`
              instances.
          """),
    "compiler_flags": attrs.list(attrs.arg(), default = [], doc = """
              The set of additional compiler flags.
          """),
    "add_hermetic_arguments": attrs.bool(default = True, doc = """
              If true, the following arguments are passed to the compiler: "/noconfig", "/nostdlib" and "/nosdkpath".
              These attributes prevent loading of default assemblies by the compiler so that they can be explicitly
              controlled in Buck2.
          """),
}

csharp_library = prelude_rule(
    name = "csharp_library",
    docs = """
        A csharp\\_library() rule builds a .Net library from the supplied set of C# source files
         and dependencies by invoking csc.
    """,
    examples = """
        ```python
        csharp_library(
          name = 'simple',
          dll_name = 'Cake.dll',
          framework_ver = 'net46',
          srcs = [
            'Hello.cs',
          ],
          deps=[
            ':other',
            'System.dll',
          ],
        )

        prebuilt_dotnet_library(
          name = 'other',
          assembly = 'other-1.0.dll',
        )
        ```
    """,
    further = None,
    attrs = (
        # @unsorted-dict-items
        {
            "dll_name": attrs.string(
                default = "",
                doc = """
                The output name of the dll. This allows you to specify the name of
                 the dll exactly. When this is not set, the dll will be named after
                 the short name of the target.
            """),
        }
        | _CSHARP_LIBRARY_OR_EXE_ATTRIBUTES
        | buck.licenses_arg()
        | buck.labels_arg()
        | buck.contacts_arg()
    ),
)

csharp_binary = prelude_rule(
    name = "csharp_binary",
    docs = """
        A csharp\\_binary() rule builds a .Net library from the supplied set of C# source files
         and dependencies by invoking csc.
    """,
    examples = """
        ```python
        csharp_binary(
          name = 'simple',
          exe_name = 'Cake.exe',
          framework_ver = 'net46',
          srcs = [
            'Hello.cs',
          ],
          deps=[
            ':other',
            'System.dll',
          ],
        )

        prebuilt_dotnet_library(
          name = 'other',
          assembly = 'other-1.0.dll',
        )
        ```
    """,
    further = None,
    attrs = (
        # @unsorted-dict-items
        {
            "exe_name": attrs.string(default = "", doc = """
                The output name of the executable. This allows you to specify the name of
                 the executable exactly. When this is not set, the executable will be named after
                 the short name of the target.
            """),
        } |
        _CSHARP_LIBRARY_OR_EXE_ATTRIBUTES |
        buck.licenses_arg() |
        buck.labels_arg() |
        buck.contacts_arg()
    ),
)

prebuilt_dotnet_library = prelude_rule(
    name = "prebuilt_dotnet_library",
    docs = """
        A `prebuilt_dotnet_library()` rule is used to include
        prebuilt .Net assembles into your .Net code.
    """,
    examples = """
        ```python
        prebuilt_dotnet_library(
          name = 'log4net',
          assembly = 'log4net.dll',
        )

        csharp_library(
          name = 'example',
          srcs = [
            'Hello.cs',
          ],
          framework_ver = 'net46',
          deps = [
            ':log4net',
            'System.dll',
          ],
        )
        ```
    """,
    further = None,
    attrs = (
        # @unsorted-dict-items
        {
            "assembly": attrs.source(
                doc = """
                The path to the DLL that this rule provides.
            """
            ),
        }
        | buck.licenses_arg()
        | buck.labels_arg()
        | buck.contacts_arg()
    ),
)

dotnet_rules = struct(
    csharp_library = csharp_library,
    csharp_binary = csharp_binary,
    prebuilt_dotnet_library = prebuilt_dotnet_library,
)