Add import_nuget_package (#48)

WORKSPACE

@@ -4,8 +4,24 @@ load(
     "@d2l_rules_csharp//csharp:defs.bzl",
     "csharp_register_toolchains",
     "csharp_repositories",
+    "import_nuget_package",
 )
 
 csharp_repositories()
 
 csharp_register_toolchains()
+
+# These are some examples.
+# Should this go here? Should we have a WORKSPACE inside csharp/ and one in
+# examples/?
+
+import_nuget_package(
+    name = "ExamplePackageFolder",
+    dir = "examples/import_nuget_package/ExamplePackageFolder",
+)
+
+import_nuget_package(
+    name = "ExampleNupkg",
+    file = "examples/import_nuget_package/Example.nupkg",
+    sha256 = "a658761334ffab1773c10dc53c7aa964f61a793963bb8111d416d2e1e1e95635",
+)

csharp/defs.bzl

@@ -21,7 +21,8 @@ load(
     _import_multiframework_library = "import_multiframework_library",
 )
 load(
-    "//csharp/private:rules/nuget.bzl",
+    "//csharp/private:macros/nuget.bzl",
+    _import_nuget_package = "import_nuget_package",
     _nuget_package = "nuget_package",
 )
 load(
@@ -36,5 +37,6 @@ csharp_register_toolchains = _csharp_register_toolchains
 csharp_repositories = _csharp_repositories
 import_multiframework_library = _import_multiframework_library
 import_library = _import_library
+import_nuget_package = _import_nuget_package
 nuget_package = _nuget_package
 setup_basic_nuget_package = _setup_basic_nuget_package

csharp/private/macros/nuget.bzl

@@ -0,0 +1,106 @@
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+def _get_build_file_content(build_file, build_file_content):
+    if build_file == None and build_file_content == None:
+        return """
+load("@d2l_rules_csharp//csharp:defs.bzl", "setup_basic_nuget_package")
+setup_basic_nuget_package()
+"""
+
+    return build_file_content
+
+def import_nuget_package(
+        name,
+        dir = None,
+        file = None,
+        build_file = None,
+        build_file_content = None,
+        sha256 = None):
+    """Import a vendored NuGet package from either a directory or .nupkg file.
+
+    Rather than downloading the package over HTTP from a package source, an
+    extracted package directory or a .nupkg file can be used. These may be
+    checked into your repository within your workspace, or somewhere else on
+    your disk.
+
+    Exactly one of either the dir or file arguments must be provided. They can
+    either be a relative path in the workspace, or an absolute path. Note that
+    paths on Windows use forward slashes.
+
+    At most one of build_file or build_file_content may be provided. If neither
+    are, a default BUILD file will be used that makes a "best effort" to wire
+    up the package. See docs/UsingNuGetPacakges.md for more info.
+
+    Args:
+      name: A unique name for the package's workspace.
+      dir: A directory containing an extracted package.
+      file: A path to a nupkg file
+      build_file: The path to a BUILD file to use for the package.
+      build_file_content: A string containing the contents of a BUILD file.
+      sha256: The SHA256 of the package.
+
+        This is only used when importing nupkg files. You may or may not find
+        it useful, but it will silence a DEBUG message from Bazel regarding
+        reproducibility.
+    """
+
+    if dir == None and file == None:
+        fail("At least one of dir or file must be provided.")
+    if dir != None and file != None:
+        fail("Only one of dir or file may be provided.")
+
+    build_file_content = _get_build_file_content(build_file, build_file_content)
+
+    if dir != None:
+        native.new_local_repository(
+            name = name,
+            build_file = build_file,
+            build_file_content = build_file_content,
+            path = dir,
+        )
+    else:
+        http_archive(
+            name = name,
+            urls = ["file:" + file],
+            type = "zip",
+            sha256 = sha256,
+            build_file = build_file,
+            build_file_content = build_file_content,
+        )
+
+def nuget_package(
+        name,
+        package,
+        version,
+        sha256 = None,
+        build_file = None,
+        build_file_content = None):
+    """Download an external NuGet package.
+
+    At most one of build_file or build_file_content may be provided. If neither
+    are, a default BUILD file will be used that makes a "best effort" to wire
+    up the package. See docs/UsingNuGetPacakges.md for more info.
+
+    Args:
+      name: A unique name for the package's workspace.
+      package: The name of the package in the NuGet feed.
+      sha256: The SHA256 of the package.
+      build_file: The path to a BUILD file to use for the package.
+      build_file_content: A string containing the contents of a BUILD file.
+    """
+
+    urls = [s + "/" + package + "/" + version for s in [
+        # TODO: allow this to be configured
+        "https://www.nuget.org/api/v2/package",
+    ]]
+
+    build_file_content = _get_build_file_content(build_file, build_file_content)
+
+    http_archive(
+        name = name,
+        urls = urls,
+        type = "zip",
+        sha256 = sha256,
+        build_file = build_file,
+        build_file_content = build_file_content,
+    )

csharp/private/macros/setup_basic_nuget_package.bzl

@@ -39,7 +39,7 @@ def setup_basic_nuget_package():
        We are limited by the fact that Bazel does not allow the analysis phase to
        read the contents of source files, e.g. to correctly configure deps. For
        more advanced usages a BUILD file will need to be generated outside of
-       Bazel.
+       Bazel. See docs/UsingNuGetPackages.md for more info.
 
        This has to be public so that packages can call it but you probably
        shouldn't use it directly.

csharp/private/repositories.bzl

@@ -1,4 +1,4 @@
-load(":rules/nuget.bzl", "nuget_package")
+load(":macros/nuget.bzl", "nuget_package")
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
 def csharp_repositories():

docs/README.md

@@ -4,4 +4,5 @@
 
 * [API Reference](APIReference.md): an inventory of public APIs for these rules.
 * [Multi-targeting Design](MultiTargetingDesign.md): an overview of how we support multiple concurrent target frameworks.
-* [Reference Assemblies](ReferenceAssemblies.md): details about how and why we use "reference assemblies" behind the scenes.
+* [Reference Assemblies](ReferenceAssemblies.md): details about how and why we use "reference assemblies" behind the scenes.
+* [Using NuGet Packages](UsingNuGetPackages.md): how to bring in packages and caveats.

docs/UsingNuGetPackages.md

@@ -0,0 +1,28 @@
+# Using NuGet Packages
+
+There are three options for using NuGet packages:
+
+1. Use `nuget_package` download a package from the internet.
+2. Use `import_nuget_package` to point at a directory containing the contents
+   of a package.
+3. Use `import_nuget_package` to point at a `.nupkg` file.
+
+(TODO: link to the API reference docs when we have them)
+
+When you use any of these options and don't provide either `build_file` or
+`build_file_content`, a default `BUILD` file will be used that calls the
+`setup_basic_nuget_package` macro.
+
+This macro uses `import_library` to import every DLL and
+`import_multiframework_library` to stitch them together into one target (see
+[docs/MultiTargetingDesign.md](docs/MultiTargetingDesign.md) for more info).
+
+The downside to this is that it always leaves `deps` empty for these targets,
+because of limitations with how Bazel works. Your options are:
+
+1. Create a better `BUILD` file from scratch (we should provide a tool to do
+   this) and use `build_file`/`build_file_content`.
+2. Always add the transitive references of your packages to your `deps` when
+   you reference the package.
+
+

examples/basic/BUILD

@@ -2,7 +2,6 @@ load(
     "@d2l_rules_csharp//csharp:defs.bzl",
     "csharp_binary",
     "csharp_library",
-    "import_multiframework_library",
     "csharp_nunit_test",
 )
 

examples/import_nuget_package/BUILD

@@ -0,0 +1,10 @@
+load("@d2l_rules_csharp//csharp:defs.bzl", "csharp_library")
+
+csharp_library(
+    name = "Demo",
+    srcs = ["Class.cs"],
+    deps = [
+        "@ExampleNupkg//:SomePackage",
+        "@ExamplePackageFolder//:SomePackage",
+    ],
+)

examples/import_nuget_package/ExamplePackageFolder/SomePackage.nuspec

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
+  <metadata>
+    <id>SomePackage</id>
+    <version>1.0.0</version>
+    <authors>SomePackage</authors>
+    <owners>SomePackage</owners>
+    <requireLicenseAcceptance>false</requireLicenseAcceptance>
+    <description>Package Description</description>
+    <dependencies>
+      <group targetFramework=".NETStandard2.0" />
+    </dependencies>
+  </metadata>
+</package>

examples/import_nuget_package/ExamplePackageFolder/[Content_Types].xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" />
+  <Default Extension="psmdcp" ContentType="application/vnd.openxmlformats-package.core-properties+xml" />
+  <Default Extension="dll" ContentType="application/octet" />
+  <Default Extension="nuspec" ContentType="application/octet" />
+</Types>

examples/import_nuget_package/ExamplePackageFolder/_rels/.rels

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Type="http://schemas.microsoft.com/packaging/2010/07/manifest" Target="/SomePackage.nuspec" Id="R7179db3dd16f457c" />
+  <Relationship Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="/package/services/metadata/core-properties/fdefc5b4605a42bf89f0b27823d8a999.psmdcp" Id="Rafabd6e52b094942" />
+</Relationships>

examples/import_nuget_package/ExamplePackageFolder/package/services/metadata/core-properties/fdefc5b4605a42bf89f0b27823d8a999.psmdcp

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<coreProperties xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.openxmlformats.org/package/2006/metadata/core-properties">
+  <dc:creator>SomePackage</dc:creator>
+  <dc:description>Package Description</dc:description>
+  <dc:identifier>SomePackage</dc:identifier>
+  <version>1.0.0</version>
+  <keywords></keywords>
+  <lastModifiedBy>NuGet.Build.Tasks.Pack, Version=4.9.4.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35;</lastModifiedBy>
+</coreProperties>

examples/import_nuget_package/README.md

@@ -0,0 +1,9 @@
+# `import_nuget_package` example
+
+This example demonstrates using vendored NuGet packages. There are two ways to
+do this: via a `.nupkg` file (which is a `.zip` file) or an extracted `.nupkg`
+file.
+
+The packages are defined in our [`WORKSPACE` file](../../WORKSPACE). This
+folder contains the vendored packages and an example `csharp_library` that uses
+them.