source-dists.rst 2.6KB

5 yıl önce
5 yıl önce
5 yıl önce
5 yıl önce
5 yıl önce
5 yıl önce
5 yıl önce
5 yıl önce
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768
  1. Source Distributions
  2. ####################
  3. A *source distribution* (often abbreviated as "sdist") is ``dds``'s primary
  4. format for consuming and distributing packages. A source distribution, in
  5. essence, is a :ref:`package root <pkgs.pkg-root>` that contains only the files
  6. necessary for ``dds`` to reproduce the full build of all libraries in the
  7. package. The source distribution retains the directory structure of every
  8. :ref:`source root <pkgs.source-root>` of the original package, and thus retains
  9. the header structure thereof. In this way, the ``#include`` directives to use a
  10. library in a source distribution are identical to if the libraries therein were
  11. directly part of the consuming project.
  12. Generating a Source Distribution
  13. ********************************
  14. Generating a source distribution from a project directory is done with the
  15. ``sdist`` subcommand::
  16. > dds pkg create
  17. The above command can be executed within a package root, and the result will be
  18. a gzip'd tar archive that reproduces the package's filesystem structure, but
  19. only maintaining the files that are necessary for ``dds`` to reproduce a build
  20. of that package.
  21. The ``--project=<dir>`` flag can be provided to override the directory that
  22. ``dds`` will use as the package root. The default is the current working
  23. directory.
  24. The ``--out=<path>`` flag can be provided to override the destination path of
  25. the archive. The path should not name an existing file or directory. By default,
  26. ``dds`` will generate a source distribution in the working directory with the
  27. pattern ``<name>@<version>.tar.gz``. If the ``--replace`` flag is provided,
  28. then ``dds`` will overwrite the destination if it names an existing file or
  29. directory.
  30. .. _sdist.import:
  31. Importing a Source Distribution
  32. *******************************
  33. Given a source distribution archive, one can import the package into the local
  34. package cache with a single command::
  35. > dds pkg import some-package@1.2.3.tar.gz
  36. You can also specify an HTTP or HTTPS URL to download a source distribution
  37. archive to import without downloading it separately::
  38. > dds pkg import https://example.org/path/to/sdist.tar.gz
  39. Alternatively, if a directory correctly models a source distribution, then
  40. that directory can be imported in the same manner::
  41. > dds pkg import /path/to/some/project
  42. Importing a package will allow projects on the system to use the imported
  43. package as a dependency.
  44. .. note::
  45. If one tries to import a package root into the cache that already contains a
  46. package with a matching identifier, ``dds`` will issue an error. This
  47. behavior can be overridden by providing ``--if-exists=replace`` on the
  48. command-line.