doc: Use CONFIG_SITE variable instead of --prefix option #17934

pull hebasto wants to merge 1 commits into bitcoin:master from hebasto:20200115-prefix-depends changing 3 files +11 −9
  1. hebasto commented at 8:17 PM on January 15, 2020: member

    The current examples of --prefix=... option usage to point configure script to appropriate depends directory is not standard. This causes some confusion and a bit of inconvenience.

    Consider a CentOS 7 32 bit system. Packages libdb4-devel, libdb4-cxx-devel, miniupnpc-devel and zeromq-devel are unavailable from repos. After recommended build with depends:

    cd depends
make
cd ..
./autogen.sh
./configure --prefix=$PWD/depends/i686-pc-linux-gnu
make

    a user is unable to make install compiled binaries neither locally (to ~/.local) nor system-wide (to /usr/local) as --prefix is set already.

    Meanwhile, the standard approach with using config.site files allows both possibilities:

    cd depends
make
cd ..
./autogen.sh
CONFIG_SITE=$PWD/depends/i686-pc-linux-gnu/share/config.site ./configure --prefix ~/.local
make
make install

    or

    CONFIG_SITE=$PWD/depends/i686-pc-linux-gnu/share/config.site ./configure
make
sudo make install  # install to /usr/local

    Moreover, this approach is used in Gitian descriptors already.

  2. hebasto commented at 8:20 PM on January 15, 2020: member

    @practicalswift #14959 (comment):

    FWIW you're not alone here: I found the use of --prefix (for anything beyond the ordinary meaning of installation destination) unintuitive too :-)

    #16691 (comment):

    Should it be clarified that --prefix is used not in its usual meaning of "when you run ./configure --prefix=/foo/bar, you are indicating that the software should be installed under the /foo/bar directory"?

    That seems to be a recurring source of confusion.

    Has it been discussed if we could use something else than --prefix for the "where to find dependencies"-meaning we're talking about here?

    ping @ryanofsky @fanquake

  3. DrahtBot added the label Build system on Jan 15, 2020
  4. DrahtBot added the label Docs on Jan 15, 2020
  5. ryanofsky commented at 8:56 PM on January 15, 2020: member

    This change seems clearer to me and I think it's an improvement. But now the documentation doesn't seem to mention the prefix path at all, so it's not clear that binaries will be installed in depends/<host-platform-triplet>. It might be worth mentioning in these documents where depends build outputs will be installed if the prefix is no longer explicit in the instructions

  6. hebasto commented at 9:01 PM on January 15, 2020: member

    This change seems clearer to me and I think it's an improvement. But now the documentation doesn't seem to mention the prefix path at all, so it's not clear that binaries will be installed in depends/<host-platform-triplet>. It might be worth mentioning in these documents where depends build outputs will be installed if the prefix is no longer explicit in the instructions

    Do you mean copy-paste from ./configure --help ?

    Installation directories:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [PREFIX]

By default, `make install' will install all the files in
`/usr/local/bin', `/usr/local/lib' etc.  You can specify
an installation prefix other than `/usr/local' using `--prefix',
for instance `--prefix=$HOME'.
  7. ryanofsky commented at 9:41 PM on January 15, 2020: member

    Do you mean copy-paste from ./configure --help ?

    I'm suggesting adding a sentence like: "The default install prefix when using config.site is --prefix=depends/<host-platform-triplet>, so depends build outputs will be installed in that location."

    Without this PR, the install location is more obvious because --prefix is explicit. The install location is less clear with this PR because it stops mentioning --prefix.

  8. fanquake requested review from theuni on Jan 16, 2020
  9. fanquake commented at 12:01 AM on January 16, 2020: member

    ~0. It has annoyed me for a while that we've been inconsistent with --prefix and CONFIG_SITE usage in our docs, and I was going to change the windows docs to use --prefix at one point.

    Consider a CentOS 7 32 bit system.

    Is this the only system where this is an issue?

    I know @theuni is busy, but I'd like his thoughts here as well.

  10. hebasto commented at 6:17 AM on January 16, 2020: member

    @fanquake

    ~0. It has annoyed me for a while that we've been inconsistent with --prefix and CONFIG_SITE usage in our docs, and I was going to change the windows docs to use --prefix at one point.

    Using --prefix in a such unusual way looks a bit like a hack. And the windows docs is ok, IMO.

    Consider a CentOS 7 32 bit system.

    Is this the only system where this is an issue?

    This issue is not CentOS specific as using --prefix make it impossible to make install compiled binaries neither locally (to ~/.local) nor system-wide (to /usr/local) on every system. But on other systems a user could get binaries in other ways (https://bitcoincore.org/en/download/).

  11. hebasto commented at 7:09 AM on January 16, 2020: member

    @ryanofsky

    I'm suggesting adding a sentence like: "The default install prefix when using config.site is --prefix=depends/<host-platform-triplet>, so depends build outputs will be installed in that location."

    IIUC, "depends build outputs" (boost, qt, zmq, ...) always are placed in depends/<host-platform-triplet> directory. And prefix is used by make install as a target to copy binaries and libraries from src tree.

    What are reasons to install to depends/<host-platform-triplet>? /home/hebasto/github/bitcoin/depends/x86_64-pc-linux-gnu/bin/bitcoind seems not very useful. /home/hebasto/.local/bin/bitcoind or /usr/local/bitcoind looks much better, IMO.

    Without this PR, the install location is more obvious because --prefix is explicit. The install location is less clear with this PR because it stops mentioning --prefix.

    Without this PR mentioning prefix was mandatory as its usage was non-standard and there was a discrepancy between our docs and autotools docs (and configure --help).

    With this PR a user who going to use make install command could use our depends docs, and prefix in a usual and well-documented (by autotools) way to point to a desired install location.

  12. ryanofsky commented at 12:19 PM on January 16, 2020: member

    Code review ACK c8e20035b088afeb731f4427e2f874e3291388a8. Agree that referencing the config.site file specifically is a not only clearer than current prefix magic but also more flexible, as in in the centos example.

    I don't understand this comment at all: #17934 (comment). I like the PR. I'm an only trying to suggest adding another sentence to the documentation. But it's fine not to add it.

  13. hebasto commented at 12:44 PM on January 16, 2020: member

    @ryanofsky Sorry, Russel. I did not want to be rude. My native language is not English, as you know. I was confused with "depends build outputs will be installed in that location" phrase. Actually, I do not understand its meaning now.

  14. hebasto commented at 12:56 PM on January 16, 2020: member

    Agree that referencing the config.site file specifically is a not only clearer than current prefix magic but also more flexible, as in in the centos example.

    More details from The Autoconf Manual - 15.8:

    If the environment variable CONFIG_SITE is set, configure uses its value as the name of a shell script to read; it is recommended that this be an absolute file name. Otherwise, it reads the shell script prefix/share/config.site if it exists, then prefix/etc/config.site if it exists.

  15. Sjors commented at 9:36 AM on January 17, 2020: member

    Concept ACK.

    Unfortunately CONFIG_SITE isn't remembered between configure runs. This causes a problem when you switch branches or pull master sometimes, when configure is automatically re-run, it forgets about using depends.

  16. hebasto commented at 9:45 AM on January 17, 2020: member

    @Sjors

    Unfortunately CONFIG_SITE isn't remembered between configure runs. This causes a problem when you switch branches or pull master sometimes, when configure is automatically re-run, it forgets about using depends.

    Do you mean that --prefix=... option is remembered in mentioned circumstances?

  17. Sjors commented at 10:26 AM on January 17, 2020: member

    I believe so yes. Though hopefully there's a way to make it remember the config_site too.

  18. hebasto commented at 8:30 AM on March 9, 2020: member

    @theuni from #8167:

    To make my life easier while I was in there, I fixed up depends to play nice with CONFIG_SITE, which can be used now instead of abusing --prefix, though the --prefix hack still works fine.

  19. in depends/README.md:17 in c8e20035b0 outdated 
      11 | @@ -12,15 +12,16 @@ For example:
  12 |  
  13 |      make HOST=x86_64-w64-mingw32 -j4
  14 |  
  15 | -**Bitcoin Core's configure script by default will ignore the depends output.** In
  16 | +**Bitcoin Core's `configure` script by default will ignore the depends output.** In
  17 |  order for it to pick up libraries, tools, and settings from the depends build,
  18 | -you must point it at the appropriate `--prefix` directory generated by the
  19 | -build. In the above example, a prefix dir named x86_64-w64-mingw32 will be
  20 | +you must set `CONFIG_SITE` environment variable to appropriate
    fanquake commented at 6:19 AM on April 8, 2021:

    you must set the CONFIG_SITE environment variable to point to a config.site settings file. In the above example, a file named depends/x86_64-w64-mingw32/share/config.site will be created. To use it during compilation:

    CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure

    hebasto commented at 9:35 AM on April 9, 2021:

    Thanks! Updated.

  20. fanquake commented at 6:19 AM on April 8, 2021: member

    Can you rebase this, and update the use of --prefix in the multiprocess documentation.

  21. doc: Use CONFIG_SITE instead of --prefix 223b1ba7d9
  22. hebasto force-pushed on Apr 9, 2021
  23. hebasto commented at 9:34 AM on April 9, 2021: member

    Updated c8e20035b088afeb731f4427e2f874e3291388a8 -> 223b1ba7d90509a47ea07af46f4b9c3b8efbc9f8 (pr17934.01 -> pr17934.02):

    I'm suggesting adding a sentence like: "The default install prefix when using config.site is --prefix=depends/<host-platform-triplet>, so depends build outputs will be installed in that location."

  24. practicalswift commented at 7:17 PM on April 9, 2021: contributor

    Concept ACK

    Thanks for fixing this. I've always found our use of --prefix somewhat unintuitive since it deviates from the typical meaning.

  25. practicalswift commented at 7:18 PM on April 9, 2021: contributor

    ACK 223b1ba7d90509a47ea07af46f4b9c3b8efbc9f8: patch looks correct

  26. in depends/README.md:24 in 223b1ba7d9 
      25 | -    ./configure --prefix=$PWD/depends/x86_64-w64-mingw32
  26 | +    CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure
  27 |  
  28 | -Common `host-platform-triplets` for cross compilation are:
  29 | +The default install prefix when using `config.site` is `--prefix=depends/<host-platform-triplet>`,
  30 | +so depends build outputs will be installed in that location.
    fanquake commented at 1:33 AM on April 10, 2021:

    By "depends build outputs" I'm assuming you mean things like the fontconfig tools, which will end up installed into depends/<host-platform-triplet>. i.e:

    # ls depends/x86_64-pc-linux-gnu/bin/
event_rpcgen.py  fc-cache  fc-cat  fc-list  fc-match  fc-pattern  fc-query  fc-scan  fc-validate  freetype-config  xmlwf

    Is that correct?

    hebasto commented at 3:26 PM on April 10, 2021:

    All of the dependency packages are installed into depends/<host-platform-triplet>, using bin, lib and other subdirectories.

    The make -C depends rightfully reports:

    copying packages: native_b2 boost libevent qt expat libxcb xcb_proto libXau xproto freetype fontconfig libxkbcommon qrencode bdb sqlite miniupnpc libnatpmp zeromq
to: /home/hebasto/GitHub/bitcoin/depends/x86_64-pc-linux-gnu

    Not to be confused with the default --prefix for Bitcoin Core, that is /usr/local. That means make install will install bitcoind into /usr/local/bin.

  27. fanquake approved
  28. fanquake commented at 1:15 PM on April 13, 2021: member

    ACK 223b1ba7d90509a47ea07af46f4b9c3b8efbc9f8

  29. fanquake merged this on Apr 13, 2021
  30. fanquake closed this on Apr 13, 2021
  31. hebasto deleted the branch on Apr 13, 2021
  32. sidhujag referenced this in commit b51a80333d on Apr 13, 2021
  33. hebasto commented at 8:08 AM on April 20, 2022: member

    @Sjors

    Unfortunately CONFIG_SITE isn't remembered between configure runs. This causes a problem when you switch branches or pull master sometimes, when configure is automatically re-run, it forgets about using depends.

    Passing CONFIG_SITE to configure as a parameter

    $ ./configure --prefix ~/.local CONFIG_SITE=$PWD/depends/i686-pc-linux-gnu/share/config.site

    should work in such cases.

  34. DrahtBot locked this on Apr 20, 2023
Contributors
hebastoryanofskyfanquakeSjorspracticalswift


theuni

Labels
DocsBuild system
Linked (view graph)
#16691 doc: improve depends prefix documentation
github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-04-22 18:14 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me