[dpdk-dev,09/11] doc: refresh headers list
Commit Message
Since we are going to remove a header in next commit, let's first refresh
documentation.
Signed-off-by: David Marchand <david.marchand@6wind.com>
---
doc/guides/prog_guide/dev_kit_build_system.rst | 57 +++++++++++++++++---------
1 file changed, 38 insertions(+), 19 deletions(-)
Comments
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of David Marchand
> Sent: Sunday, January 10, 2016 12:51 PM
> To: dev@dpdk.org
> Cc: thomas.monjalon@dpdk.org
> Subject: [dpdk-dev] [PATCH 09/11] doc: refresh headers list
>
> Since we are going to remove a header in next commit, let's first refresh
> documentation.
Hi,
I don't like these parts of the docs that list files since they
go out of date quite easily and, in general, the same information
can be conveyed by just listing the directories. (That isn't
future-proof either but it should be less subject to change.)
In this case you could just remove everything in the console section
after the output from "ls x86_64-native-linuxapp-gcc" like this:
Each build directory contains include files, libraries, and applications like the following::
$ ls
app tools
config MAINTAINERS
Makefile GNUmakefile
drivers mk
examples pkg
doc README
lib scripts
LICENSE.GPL LICENSE.LGPL
i686-native-linuxapp-gcc x86_64-native-linuxapp-gcc
i686-native-linuxapp-icc x86_64-native-linuxapp-icc
$ ls x86_64-native-linuxapp-gcc
app build include kmod lib Makefile
John.
--
Hello John,
On Tue, Jan 12, 2016 at 3:06 PM, Mcnamara, John <john.mcnamara@intel.com> wrote:
>> -----Original Message-----
>> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of David Marchand
>> Sent: Sunday, January 10, 2016 12:51 PM
>> To: dev@dpdk.org
>> Cc: thomas.monjalon@dpdk.org
>> Subject: [dpdk-dev] [PATCH 09/11] doc: refresh headers list
>>
>> Since we are going to remove a header in next commit, let's first refresh
>> documentation.
>
> I don't like these parts of the docs that list files since they
> go out of date quite easily and, in general, the same information
> can be conveyed by just listing the directories. (That isn't
> future-proof either but it should be less subject to change.)
Well, we could imagine something automatic (in the build process), but
I agree that the quickest solution is to get rid of it.
>
> In this case you could just remove everything in the console section
> after the output from "ls x86_64-native-linuxapp-gcc" like this:
>
>
> Each build directory contains include files, libraries, and applications like the following::
>
> $ ls
> app tools
> config MAINTAINERS
> Makefile GNUmakefile
> drivers mk
> examples pkg
> doc README
> lib scripts
> LICENSE.GPL LICENSE.LGPL
> i686-native-linuxapp-gcc x86_64-native-linuxapp-gcc
> i686-native-linuxapp-icc x86_64-native-linuxapp-icc
>
> $ ls x86_64-native-linuxapp-gcc
> app build include kmod lib Makefile
>
Well, from my pov, it is the same issue here.
How about just removing all those files listings ?
I am not sure they really help.
If we go with this, I will send this patch out of the series since it
would not really belong to it.
Regards,
2016-01-16 16:10, David Marchand:
> On Tue, Jan 12, 2016 at 3:06 PM, Mcnamara, John <john.mcnamara@intel.com> wrote:
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of David Marchand
> >> Since we are going to remove a header in next commit, let's first refresh
> >> documentation.
> >
> > I don't like these parts of the docs that list files since they
> > go out of date quite easily and, in general, the same information
> > can be conveyed by just listing the directories. (That isn't
> > future-proof either but it should be less subject to change.)
+1
> > $ ls
> > app tools
> > config MAINTAINERS
> > Makefile GNUmakefile
> > drivers mk
> > examples pkg
> > doc README
> > lib scripts
> > LICENSE.GPL LICENSE.LGPL
> > i686-native-linuxapp-gcc x86_64-native-linuxapp-gcc
> > i686-native-linuxapp-icc x86_64-native-linuxapp-icc
> >
> > $ ls x86_64-native-linuxapp-gcc
> > app build include kmod lib Makefile
> >
>
> Well, from my pov, it is the same issue here.
> How about just removing all those files listings ?
> I am not sure they really help.
+1
> -----Original Message-----
> From: David Marchand [mailto:david.marchand@6wind.com]
> Sent: Saturday, January 16, 2016 3:11 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org; Thomas Monjalon
> Subject: Re: [dpdk-dev] [PATCH 09/11] doc: refresh headers list
>
> Hello John,
>
> On Tue, Jan 12, 2016 at 3:06 PM, Mcnamara, John <john.mcnamara@intel.com>
> wrote:
> >> -----Original Message-----
> >> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of David Marchand
> >> Sent: Sunday, January 10, 2016 12:51 PM
> >> To: dev@dpdk.org
> >> Cc: thomas.monjalon@dpdk.org
> >> Subject: [dpdk-dev] [PATCH 09/11] doc: refresh headers list
> >>
> >> Since we are going to remove a header in next commit, let's first
> >> refresh documentation.
> >
> > I don't like these parts of the docs that list files since they go out
> > of date quite easily and, in general, the same information can be
> > conveyed by just listing the directories. (That isn't future-proof
> > either but it should be less subject to change.)
>
> Well, we could imagine something automatic (in the build process), but I
> agree that the quickest solution is to get rid of it.
>
> >
> > In this case you could just remove everything in the console section
> > after the output from "ls x86_64-native-linuxapp-gcc" like this:
> >
> >
> > Each build directory contains include files, libraries, and applications
> like the following::
> >
> > $ ls
> > app tools
> > config MAINTAINERS
> > Makefile GNUmakefile
> > drivers mk
> > examples pkg
> > doc README
> > lib scripts
> > LICENSE.GPL LICENSE.LGPL
> > i686-native-linuxapp-gcc x86_64-native-linuxapp-gcc
> > i686-native-linuxapp-icc x86_64-native-linuxapp-icc
> >
> > $ ls x86_64-native-linuxapp-gcc
> > app build include kmod lib Makefile
> >
>
> Well, from my pov, it is the same issue here.
> How about just removing all those files listings ?
> I am not sure they really help.
Hi,
I'm fine with that. I don't think the file listing adds much information to the previous paragraph.
Or we could just add text that leaves out some of the information
so that the reader doesn’t expect an exact representation and isn't
confused when their file structure doesn't match. Something like:
$ ls
...
app
config
doc
drivers
examples
lib
...
i686-native-linuxapp-gcc
i686-native-linuxapp-icc
x86_64-native-linuxapp-gcc
x86_64-native-linuxapp-icc
...
John.
--
@@ -89,25 +89,44 @@ Each build directory contains include files, libraries, and applications:
~/DEV/DPDK$ ls i686-native-linuxapp-gcc/include/
- arch rte_cpuflags.h rte_memcpy.h
- cmdline_cirbuf.h rte_cycles.h rte_memory.h
- cmdline.h rte_debug.h rte_mempool.h
- cmdline_parse_etheraddr.h rte_eal.h rte_memzone.h
- cmdline_parse.h rte_errno.h rte_pci_dev_ids.h
- cmdline_parse_ipaddr.h rte_ethdev.h rte_pci.h
- cmdline_parse_num.h rte_ether.h rte_per_lcore.h
- cmdline_parse_portlist.h rte_fbk_hash.h rte_prefetch.h
- cmdline_parse_string.h rte_hash_crc.h rte_random.h
- cmdline_rdline.h rte_hash.h rte_ring.h
- cmdline_socket.h rte_interrupts.h rte_rwlock.h
- cmdline_vt100.h rte_ip.h rte_sctp.h
- exec-env rte_jhash.h rte_spinlock.h
- rte_alarm.h rte_launch.h rte_string_fns.h
- rte_atomic.h rte_lcore.h rte_tailq.h
- rte_branch_prediction.h rte_log.h rte_tcp.h
- rte_byteorder.h rte_lpm.h rte_timer.h
- rte_common.h rte_malloc.h rte_udp.h
- rte_config.h rte_mbuf.h
+ cmdline_cirbuf.h rte_eal_memconfig.h rte_per_lcore.h
+ cmdline.h rte_errno.h rte_pipeline.h
+ cmdline_parse_etheraddr.h rte_eth_af_packet.h rte_port_ethdev.h
+ cmdline_parse.h rte_eth_bond_8023ad.h rte_port_frag.h
+ cmdline_parse_ipaddr.h rte_eth_bond.h rte_port.h
+ cmdline_parse_num.h rte_eth_ctrl.h rte_port_ras.h
+ cmdline_parse_portlist.h rte_ethdev.h rte_port_ring.h
+ cmdline_parse_string.h rte_ether.h rte_port_sched.h
+ cmdline_rdline.h rte_eth_ring.h rte_port_source_sink.h
+ cmdline_socket.h rte_fbk_hash.h rte_power.h
+ cmdline_vt100.h rte_hash_crc.h rte_prefetch.h
+ exec-env rte_hash.h rte_random.h
+ generic rte_hexdump.h rte_red.h
+ rte_acl.h rte_icmp.h rte_reorder.h
+ rte_acl_osdep.h rte_interrupts.h rte_ring.h
+ rte_alarm.h rte_ip_frag.h rte_rtm.h
+ rte_approx.h rte_ip.h rte_rwlock.h
+ rte_arp.h rte_jhash.h rte_sched_common.h
+ rte_atomic_32.h rte_jobstats.h rte_sched.h
+ rte_atomic_64.h rte_kvargs.h rte_sctp.h
+ rte_atomic.h rte_launch.h rte_spinlock.h
+ rte_bitmap.h rte_lcore.h rte_string_fns.h
+ rte_branch_prediction.h rte_log.h rte_table_acl.h
+ rte_byteorder_32.h rte_lpm6.h rte_table_array.h
+ rte_byteorder_64.h rte_lpm.h rte_table.h
+ rte_byteorder.h rte_lru.h rte_table_hash.h
+ rte_cfgfile.h rte_malloc.h rte_table_lpm.h
+ rte_common.h rte_malloc_heap.h rte_table_lpm_ipv6.h
+ rte_compat.h rte_mbuf.h rte_table_stub.h
+ rte_config.h rte_memcpy.h rte_tailq.h
+ rte_cpuflags.h rte_memory.h rte_tcp.h
+ rte_cycles.h rte_mempool.h rte_thash.h
+ rte_debug.h rte_memzone.h rte_timer.h
+ rte_devargs.h rte_meter.h rte_udp.h
+ rte_dev.h rte_pci_dev_feature_defs.h rte_vect.h
+ rte_dev_info.h rte_pci_dev_features.h rte_version.h
+ rte_distributor.h rte_pci_dev_ids.h rte_virtio_net.h
+ rte_eal.h rte_pci.h
A build directory is specific to a configuration that includes architecture + execution environment + toolchain.