<p>I have a different approach to it. You can use this too.</p>

<ol>
<li><p>Bitcoin uses <a href="http://www.doxygen.nl/index.html" rel="noreferrer">Doxygen</a> comments to explain the code. 
You can take the most recent copy of the code, build class hierarchy yourself using Doxygen, and then navigate through the various classes.</p></li>
<li><p>The next step would be to build it and run it in -regtest mode.</p></li>
<li><p>Use gdb to add breakpoints, and inspect the flow.</p></li>
<li><p>You can start with init and util files and then go through others. They have generic code, logging and files. And then get to the net.cpp, validation.cpp to find the more detailed logic.</p></li>
<li><p>In my opinion, diving into the code, getting messy is a much better approach rather than reading more. Get dirty into the code, write some of it, get errors, and understand on the way. </p></li>
</ol>

CC BY-SA 4.0
2018-06-27T14:17:05.540Z
2018-12-16T20:30:07.217Z
2018-12-16T20:30:07.217Z
thenakulchawla
<p>I'm in my final year of college and I remember being in your exact situation 2 years ago. In my view you can adopt 2 strategies at this stage.</p>

<p>You need to understand the protocol first, and reading <a href="https://bitcoin.org/bitcoin.pdf" rel="noreferrer">Satoshi's orginal paper</a>, or any of the easier options is essential. It also helps a lot to understand the conceptual differences between bitcoin and other currencies like Ripple and Peercoin.</p>

<p>If your intention is to learn as much about the bitcoin implementation as possible, I would suggest you give up on bitcoin-core and shift to one of the python implementations. Now, there are a few quirks about the <a href="https://bitcoin.stackexchange.com/questions/41682/a-complete-bitcoin-implementation-in-python">python implementations</a>, but your learning would be much faster and you'd be in a much better position to understand the cpp code later.</p>

<p>If you want to stick to bitcoin-core, and are willing to tolerate a steep learning curve, there are still a few resources to sweeten it. You need to understand that it's not just cpp that you need to master to understand bitcoin core, but a lot of the <a href="https://en.wikipedia.org/wiki/GNU_build_system" rel="noreferrer">GNU build system, the makes and the autoconfs and such stuff</a>.</p>

<p>Now to help you understand the structure of the code in src, <a href="https://dev.visucore.com/bitcoin/doxygen/inherits.html" rel="noreferrer">you could check this out</a>.</p>

<p>Edit (7:7:2016):A lot of the new discussions in the bitcoin:core world, revolves around the CPP language itself. CPP itself undergoes considerable change every 4 years and there are many discussions around which CPP language features can be implemented/ incorporated into bitcoin-core. So it is required that you have a thorough understanding of CPP along with new language features that keep getting added, and their relations to the previous features.</p>

CC BY-SA 3.0
2016-07-07T16:12:49.697Z
Bitcoin Core is switching to C++11 in the upcoming 0.13 release. Meanwhile, C++14 is already standardized and C++17 is well underway. Stating that Bitcoin Core always uses the latest features seems like a strange statement.
Pieter Wuille
CC BY-SA 3.0
2016-07-07T17:12:37.270Z
I changed that statement to something more moderate I hope :). I'm not going to argue with Einstein about relativity. :)
user2277550
CC BY-SA 4.0
2015-12-08T05:53:24.707Z
2018-05-22T16:44:00.073Z
2018-05-22T16:44:00.073Z
user2277550
<p>The Bitcoin-qt source code grew out of the original code written by Satochi. The latter, in my opinion, is much cleaner and easier to read. I have a new book that analyzes the Statochi's original source code at lulu.com: <a href="http://www.lulu.com/shop/paul-huang/a-dissection-of-bitcoin/ebook/product-22482928.html" rel="noreferrer">A Dissection of Bitcoin</a></p>

CC BY-SA 3.0
2015-12-13T20:28:04.833Z
2015-12-13T20:28:04.833Z
Paul Huang
<p>Recently I was in a situation where I had to work on Bitcoin-core c++ code base. Being from c# background, I had the same problem which you faced. I also looked into the solutions which everyone is suggesting, still, I want to give you a more precise solution for this question:</p>

<h2>Pre-requisites</h2>

<ul>
<li>You need to understand the basic of c++ project structure. 
something like this:</li>
</ul>

<pre><code>root\
    lib\
        submodule1\
        submodule2\
        MakeFile.am
    src\
        component1\
            comp1.cpp
            comp1.h
        component2\
        main.cpp
        Makefile.am
    .gitmodules
    .gitignore
    Makefile.am
    configure.ac
    autogen.sh
</code></pre>

<p>This the very a basic project structure and it can go to a very complex one, but just to give an idea let's bear with it. I won't give you details of these files but you can always checkout out my dedicated <a href="https://github.com/Vishwas1/cppBoilerplate" rel="noreferrer">repository</a> for c++ boilerplate. Files like, <code>Makefile.am</code>, <code>configure.ac</code> etc. are there for <code>Autotools</code> or <code>GNU Build Tools</code>. Basically, Autotools is a set of tools, Autoconf, Automake, make utility and Libtools, used to build c++ project.</p>

<ul>
<li>Get the basic of <code>Autotools</code></li>
</ul>

<h2>Let's start</h2>

<ul>
<li>Download Bitcoin-core and open <code>/src/Makefile.am</code>.</li>
<li>The Bitcoin code base is a combination of several programs like <code>bitcoind</code>, <code>bitcoin-cli</code>, <code>bitcoin-tx</code> and <code>bitcoin-qt</code> . You can see these programs mentioned in <code>src/Makefile.am</code> file, search for bin_PROGRAMS macro.</li>
</ul>

<pre><code>if BUILD_BITCOIND
  bin_PROGRAMS += bitcoind
endif
if BUILD_BITCOIN_CLI
  bin_PROGRAMS += bitcoin-cli
endif
if BUILD_BITCOIN_TX
  bin_PROGRAMS += bitcoin-tx
endif
</code></pre>

<ul>
<li><em>It is important to know which executable you want to debug? - I am giving an example of <code>bitcoind</code></em></li>
<li><p>Bitcoin's developers have converted modules (consensus, server, cli, wallet, common, crypto etc.) into static libraries (.a files) so that they can be shared and used across all these programs. In order to understand how these files are managed, as I said, start looking into the <em>Makefile.am</em>, present inside src directory. For example:</p></li>
<li><p>In the bitcoin's <code>src/Makefile.am</code> file, we have <code>bitcoind</code> right? Let's search this text in that file.  You will get <code>bitcoind_SOURCES</code> and <code>bitcoind_LDADD</code> macros for the source file of that program (basically the file where main() is defined) and linked static libraries (.a files) to <code>bitcoind</code> program respectively. </p></li>
<li><p>Now let's look for one of the linked libraries, say <code>libbitcoin_server</code>, you will find <code>libbitcoin_server_a_CPPFLAGS</code>, <code>libbitcoin_server_a_CXXFLAGS</code> and <code>libbitcoin_server_a_SOURCES</code> macros. In <code>libbitcoin_server_a_SOURCES</code> macro, you have all <code>.cpp</code> and <code>.h</code> files defined there.</p></li>
</ul>

<p>I hope these would have given you some insights to start with. Soon I will be writing a blog on this topic. Will edit this answer once done.</p>

<p>EDIT: here is a <a href="https://vishwas.netlify.com/post/bitcoin-stellar-build/" rel="noreferrer">blog</a> on this topic which I have written. Hope that will help.</p>

CC BY-SA 4.0
2023-12-21T22:46:31.973Z
The link to your blog seems to be broken. Can you please update it?
Gui Imamura
CC BY-SA 4.0
2019-03-05T10:49:08.237Z
2019-03-07T19:40:04.010Z
2019-03-07T19:40:04.010Z
Vishwas Bhushan
<p>I am not a C++ pro. I read C++ as a part of my undergrad school course. I am very passionate about the future currency i.e. Bitcoin. </p>

<p>But I don't understand the source code structure. How to read the source code? As I already told I am have very basic knowledge of C++. </p>

<p>However, I can google on the way if don't understand something(functions, libraries, headers). </p>

<p>The actual problem I am facing is inside <code>src/</code> directory. I don't understand the flow of files and directories in <code>src/</code>. Which is the first file that I should probably start reading. Can any one explain me all of flow of all the project in some sort of tree like structure? </p>

<pre><code>~/GitHub/bitcoin/src
❯ ls                                                                   ✔ master
Makefile.am     coincontrol.h       miner.h         script
Makefile.bench.include  coins.cpp       net.cpp         secp256k1
Makefile.qt.include coins.h         net.h           serialize.h
Makefile.qttest.include compat          netbase.cpp     streams.h
Makefile.test.include   compat.h        netbase.h       support
addrman.cpp     compressor.cpp      noui.cpp        sync.cpp
addrman.h       compressor.h        noui.h          sync.h
alert.cpp       config          obj         test
alert.h         consensus       obj-test        threadsafety.h
amount.cpp      core_io.h       policy          timedata.cpp
amount.h        core_memusage.h     pow.cpp         timedata.h
arith_uint256.cpp   core_read.cpp       pow.h           tinyformat.h
arith_uint256.h     core_write.cpp      prevector.h     torcontrol.cpp
base58.cpp      crypto          primitives      torcontrol.h
base58.h        dbwrapper.cpp       protocol.cpp        txdb.cpp
bench           dbwrapper.h     protocol.h      txdb.h
bitcoin-cli-res.rc  hash.cpp        pubkey.cpp      txmempool.cpp
bitcoin-cli.cpp     hash.h          pubkey.h        txmempool.h
bitcoin-tx-res.rc   httprpc.cpp     qt          ui_interface.h
bitcoin-tx.cpp      httprpc.h       random.cpp      uint256.cpp
bitcoind-res.rc     httpserver.cpp      random.h        uint256.h
bitcoind.cpp        httpserver.h        rest.cpp        undo.h
bloom.cpp       init.cpp        reverselock.h       univalue
bloom.h         init.h          rpcblockchain.cpp   util.cpp
chain.cpp       key.cpp         rpcclient.cpp       util.h
chain.h         key.h           rpcclient.h     utilmoneystr.cpp
chainparams.cpp     keystore.cpp        rpcmining.cpp       utilmoneystr.h
chainparams.h       keystore.h      rpcmisc.cpp     utilstrencodings.cpp
chainparamsbase.cpp leveldb         rpcnet.cpp      utilstrencodings.h
chainparamsbase.h   limitedmap.h        rpcprotocol.cpp     utiltime.cpp
chainparamsseeds.h  main.cpp        rpcprotocol.h       utiltime.h
checkpoints.cpp     main.h          rpcrawtransaction.cpp   validationinterface.cpp
checkpoints.h       memusage.h      rpcserver.cpp       validationinterface.h
checkqueue.h        merkleblock.cpp     rpcserver.h     version.h
clientversion.cpp   merkleblock.h       scheduler.cpp       wallet
clientversion.h     miner.cpp       scheduler.h     zmq
</code></pre>

CC BY-SA 3.0
2015-12-07T22:07:12.543Z
I think the good starting point would be take an online course in C++. Otherwise you would be reading foreign language you have no idea of.
Mikko Ohtamaa
CC BY-SA 3.0
2015-12-07T22:22:52.363Z
I am aware of C++. I am also update with C++, C++14. Its just that I never worked on a big project so I don't know the workflow. @MikkoOhtamaa would you suggest me a good resource which doesn't cover the language basics and cover the advance features of the language itself? Currently I am counting on videos posted on on channel9.msdn is that fine?
abhimanyuaryan
CC BY-SA 3.0
2015-12-07T22:30:35.483Z
All Microsoft sources are pretty decent what comes to advanced C++. I also suggest you getting a good IDE which does autocompletion, code insight and such that you can get around in code tree according to code flow.
Mikko Ohtamaa
CC BY-SA 3.0
2015-12-13T21:13:35.780Z
Well, this is not a complete answer, but there is a lot of stuff in main.cpp to look at. I would start there.
Fraggle
<bitcoin-core-development><c++><open-source>
How to understand Bitcoin source code
abhimanyuaryan
# How to understand Bitcoin source code

(Asked by: username_0 on 2015-12-07)

I am not a C++ pro. I read C++ as a part of my undergrad school course. I am very passionate about the future currency i.e. Bitcoin.

But I don't understand the source code structure. How to read the source code? As I already told I am have very basic knowledge of C++.

However, I can google on the way if don't understand something(functions, libraries, headers).

The actual problem I am facing is inside `src/` directory. I don't understand the flow of files and directories in `src/`. Which is the first file that I should probably start reading. Can any one explain me all of flow of all the project in some sort of tree like structure?

```
~/GitHub/bitcoin/src
❯ ls                                                                   ✔ master
Makefile.am     coincontrol.h       miner.h         script
Makefile.bench.include  coins.cpp       net.cpp         secp256k1
Makefile.qt.include coins.h         net.h           serialize.h
Makefile.qttest.include compat          netbase.cpp     streams.h
Makefile.test.include   compat.h        netbase.h       support
addrman.cpp     compressor.cpp      noui.cpp        sync.cpp
addrman.h       compressor.h        noui.h          sync.h
alert.cpp       config          obj         test
alert.h         consensus       obj-test        threadsafety.h
amount.cpp      core_io.h       policy          timedata.cpp
amount.h        core_memusage.h     pow.cpp         timedata.h
arith_uint256.cpp   core_read.cpp       pow.h           tinyformat.h
arith_uint256.h     core_write.cpp      prevector.h     torcontrol.cpp
base58.cpp      crypto          primitives      torcontrol.h
base58.h        dbwrapper.cpp       protocol.cpp        txdb.cpp
bench           dbwrapper.h     protocol.h      txdb.h
bitcoin-cli-res.rc  hash.cpp        pubkey.cpp      txmempool.cpp
bitcoin-cli.cpp     hash.h          pubkey.h        txmempool.h
bitcoin-tx-res.rc   httprpc.cpp     qt          ui_interface.h
bitcoin-tx.cpp      httprpc.h       random.cpp      uint256.cpp
bitcoind-res.rc     httpserver.cpp      random.h        uint256.h
bitcoind.cpp        httpserver.h        rest.cpp        undo.h
bloom.cpp       init.cpp        reverselock.h       univalue
bloom.h         init.h          rpcblockchain.cpp   util.cpp
chain.cpp       key.cpp         rpcclient.cpp       util.h
chain.h         key.h           rpcclient.h     utilmoneystr.cpp
chainparams.cpp     keystore.cpp        rpcmining.cpp       utilmoneystr.h
chainparams.h       keystore.h      rpcmisc.cpp     utilstrencodings.cpp
chainparamsbase.cpp leveldb         rpcnet.cpp      utilstrencodings.h
chainparamsbase.h   limitedmap.h        rpcprotocol.cpp     utiltime.cpp
chainparamsseeds.h  main.cpp        rpcprotocol.h       utiltime.h
checkpoints.cpp     main.h          rpcrawtransaction.cpp   validationinterface.cpp
checkpoints.h       memusage.h      rpcserver.cpp       validationinterface.h
checkqueue.h        merkleblock.cpp     rpcserver.h     version.h
clientversion.cpp   merkleblock.h       scheduler.cpp       wallet
clientversion.h     miner.cpp       scheduler.h     zmq

```

**Tags:** bitcoin-core-development, c++, open-source

> **Comments:**
> **username_1**: I think the good starting point would be take an online course in C++. Otherwise you would be reading foreign language you have no idea of.  
> **username_0**: I am aware of C++. I am also update with C++, C++14. Its just that I never worked on a big project so I don't know the workflow. @username_1 would you suggest me a good resource which doesn't cover the language basics and cover the advance features of the language itself? Currently I am counting on videos posted on on channel9.msdn is that fine?  
> **username_1**: All Microsoft sources are pretty decent what comes to advanced C++. I also suggest you getting a good IDE which does autocompletion, code insight and such that you can get around in code tree according to code flow.  
> **username_2**: Well, this is not a complete answer, but there is a lot of stuff in main.cpp to look at. I would start there.  

---

## 4 answers

### Answer by username_7 on 2019-03-05. Score: 9 | Accepted answer

Recently I was in a situation where I had to work on Bitcoin-core c++ code base. Being from c# background, I had the same problem which you faced. I also looked into the solutions which everyone is suggesting, still, I want to give you a more precise solution for this question:

## Pre-requisites

* You need to understand the basic of c++ project structure.
  something like this:

```
root\
    lib\
        submodule1\
        submodule2\
        MakeFile.am
    src\
        component1\
            comp1.cpp
            comp1.h
        component2\
        main.cpp
        Makefile.am
    .gitmodules
    .gitignore
    Makefile.am
    configure.ac
    autogen.sh

```

This the very a basic project structure and it can go to a very complex one, but just to give an idea let's bear with it. I won't give you details of these files but you can always checkout out my dedicated [repository](https://github.com/Vishwas1/cppBoilerplate) for c++ boilerplate. Files like, `Makefile.am`, `configure.ac` etc. are there for `Autotools` or `GNU Build Tools`. Basically, Autotools is a set of tools, Autoconf, Automake, make utility and Libtools, used to build c++ project.

* Get the basic of `Autotools`

## Let's start

* Download Bitcoin-core and open `/src/Makefile.am`.
* The Bitcoin code base is a combination of several programs like `bitcoind`, `bitcoin-cli`, `bitcoin-tx` and `bitcoin-qt` . You can see these programs mentioned in `src/Makefile.am` file, search for bin\_PROGRAMS macro.

```
if BUILD_BITCOIND
  bin_PROGRAMS += bitcoind
endif
if BUILD_BITCOIN_CLI
  bin_PROGRAMS += bitcoin-cli
endif
if BUILD_BITCOIN_TX
  bin_PROGRAMS += bitcoin-tx
endif

```

* *It is important to know which executable you want to debug? - I am giving an example of `bitcoind`*
* Bitcoin's developers have converted modules (consensus, server, cli, wallet, common, crypto etc.) into static libraries (.a files) so that they can be shared and used across all these programs. In order to understand how these files are managed, as I said, start looking into the *Makefile.am*, present inside src directory. For example:
* In the bitcoin's `src/Makefile.am` file, we have `bitcoind` right? Let's search this text in that file. You will get `bitcoind_SOURCES` and `bitcoind_LDADD` macros for the source file of that program (basically the file where main() is defined) and linked static libraries (.a files) to `bitcoind` program respectively.
* Now let's look for one of the linked libraries, say `libbitcoin_server`, you will find `libbitcoin_server_a_CPPFLAGS`, `libbitcoin_server_a_CXXFLAGS` and `libbitcoin_server_a_SOURCES` macros. In `libbitcoin_server_a_SOURCES` macro, you have all `.cpp` and `.h` files defined there.

I hope these would have given you some insights to start with. Soon I will be writing a blog on this topic. Will edit this answer once done.

EDIT: here is a [blog](https://username_7.netlify.com/post/bitcoin-stellar-build/) on this topic which I have written. Hope that will help.

> **Comments:**
> **username_8**: The link to your blog seems to be broken. Can you please update it?  

---

### Answer by username_4 on 2015-12-08. Score: 32

I'm in my final year of college and I remember being in your exact situation 2 years ago. In my view you can adopt 2 strategies at this stage.

You need to understand the protocol first, and reading [Satoshi's orginal paper](https://bitcoin.org/bitcoin.pdf), or any of the easier options is essential. It also helps a lot to understand the conceptual differences between bitcoin and other currencies like Ripple and Peercoin.

If your intention is to learn as much about the bitcoin implementation as possible, I would suggest you give up on bitcoin-core and shift to one of the python implementations. Now, there are a few quirks about the [python implementations](https://bitcoin.stackexchange.com/questions/41682/a-complete-bitcoin-implementation-in-python), but your learning would be much faster and you'd be in a much better position to understand the cpp code later.

If you want to stick to bitcoin-core, and are willing to tolerate a steep learning curve, there are still a few resources to sweeten it. You need to understand that it's not just cpp that you need to master to understand bitcoin core, but a lot of the [GNU build system, the makes and the autoconfs and such stuff](https://en.wikipedia.org/wiki/GNU_build_system).

Now to help you understand the structure of the code in src, [you could check this out](https://dev.visucore.com/bitcoin/doxygen/inherits.html).

Edit (7:7:2016):A lot of the new discussions in the bitcoin:core world, revolves around the CPP language itself. CPP itself undergoes considerable change every 4 years and there are many discussions around which CPP language features can be implemented/ incorporated into bitcoin-core. So it is required that you have a thorough understanding of CPP along with new language features that keep getting added, and their relations to the previous features.

> **Comments:**
> **username_5**: Bitcoin Core is switching to C++11 in the upcoming 0.13 release. Meanwhile, C++14 is already standardized and C++17 is well underway. Stating that Bitcoin Core always uses the latest features seems like a strange statement.  
> **username_4**: I changed that statement to something more moderate I hope :). I'm not going to argue with Einstein about relativity. :)  

---

### Answer by username_3 on 2018-06-27. Score: 11

I have a different approach to it. You can use this too.

1. Bitcoin uses [Doxygen](http://www.doxygen.nl/index.html) comments to explain the code.
   You can take the most recent copy of the code, build class hierarchy yourself using Doxygen, and then navigate through the various classes.
2. The next step would be to build it and run it in -regtest mode.
3. Use gdb to add breakpoints, and inspect the flow.
4. You can start with init and util files and then go through others. They have generic code, logging and files. And then get to the net.cpp, validation.cpp to find the more detailed logic.
5. In my opinion, diving into the code, getting messy is a much better approach rather than reading more. Get dirty into the code, write some of it, get errors, and understand on the way.


---

### Answer by username_6 on 2015-12-13. Score: 6

The Bitcoin-qt source code grew out of the original code written by Satochi. The latter, in my opinion, is much cleaner and easier to read. I have a new book that analyzes the Statochi's original source code at lulu.com: [A Dissection of Bitcoin](http://www.lulu.com/shop/username_6/a-dissection-of-bitcoin/ebook/product-22482928.html)


---

