Move examples into subfolders, add READMEs

24 files changed, 187 insertions, 55 deletions

diff --git a/example/Makefile b/example/Makefile
deleted file mode 100644
index 14dd9fa4..00000000
--- a/example/Makefile
+++ /dev/null
@@ -1,14 +0,0 @@
-CFLAGS=-ansi -Wall -Werror -I .. -g -O0
-DEPS=../pb_decode.c ../pb_decode.h ../pb_encode.c ../pb_encode.h ../pb.h
-
-all: server client
-
-clean:
-	rm -f server client fileproto.pb.c fileproto.pb.h
-
-%: %.c $(DEPS) fileproto.pb.h fileproto.pb.c
-	$(CC) $(CFLAGS) -o $@ $< ../pb_decode.c ../pb_encode.c fileproto.pb.c common.c
-
-fileproto.pb.c fileproto.pb.h: fileproto.proto ../generator/nanopb_generator.py
-	protoc -I. -I../generator -I/usr/include -ofileproto.pb $<
-	python ../generator/nanopb_generator.py fileproto.pb
diff --git a/example_avr_double/Makefile b/example_avr_double/Makefile
deleted file mode 100644
index 74300fc6..00000000
--- a/example_avr_double/Makefile
+++ /dev/null
@@ -1,22 +0,0 @@
-CFLAGS=-Wall -Werror -I .. -g -O0
-DEPS=double_conversion.c ../pb_decode.c ../pb_decode.h ../pb_encode.c ../pb_encode.h ../pb.h
-
-all: run_tests
-
-clean:
-	rm -f test_conversions encode_double decode_double doubleproto.pb.c doubleproto.pb.h
-
-test_conversions: test_conversions.c double_conversion.c
-	$(CC) $(CFLAGS) -o $@ $^
-
-%: %.c $(DEPS) doubleproto.pb.h doubleproto.pb.c
-	$(CC) $(CFLAGS) -o $@ $< double_conversion.c ../pb_decode.c ../pb_encode.c doubleproto.pb.c
-
-doubleproto.pb.c doubleproto.pb.h: doubleproto.proto ../generator/nanopb_generator.py
-	protoc -I. -I../generator -I/usr/include -odoubleproto.pb $<
-	python ../generator/nanopb_generator.py doubleproto.pb
-
-run_tests: test_conversions encode_double decode_double
-	./test_conversions
-	./encode_double | ./decode_double
-    
diff --git a/example_unions/Makefile b/example_unions/Makefile
deleted file mode 100644
index 29514ca9..00000000
--- a/example_unions/Makefile
+++ /dev/null
@@ -1,17 +0,0 @@
-CFLAGS=-ansi -Wall -Werror -I .. -g -O0
-DEPS=../pb_decode.c ../pb_decode.h ../pb_encode.c ../pb_encode.h ../pb.h
-
-all: encode decode
-	./encode 1 | ./decode
-	./encode 2 | ./decode
-	./encode 3 | ./decode
-
-clean:
-	rm -f encode unionproto.pb.h unionproto.pb.c
-
-%: %.c $(DEPS) unionproto.pb.h unionproto.pb.c
-	$(CC) $(CFLAGS) -o $@ $< ../pb_decode.c ../pb_encode.c unionproto.pb.c
-
-unionproto.pb.h unionproto.pb.c: unionproto.proto ../generator/nanopb_generator.py
-	protoc -I. -I../generator -I/usr/include -ounionproto.pb $<
-	python ../generator/nanopb_generator.py unionproto.pb
diff --git a/examples/network_server/Makefile b/examples/network_server/Makefile
new file mode 100644
index 00000000..981f2cf9
--- /dev/null
+++ b/examples/network_server/Makefile
@@ -0,0 +1,19 @@
+CFLAGS = -ansi -Wall -Werror -g -O0
+
+# Path to the nanopb root folder
+NANOPB_DIR = ../..
+DEPS = $(NANOPB_DIR)/pb_decode.c $(NANOPB_DIR)/pb_decode.h \
+       $(NANOPB_DIR)/pb_encode.c $(NANOPB_DIR)/pb_encode.h $(NANOPB_DIR)/pb.h
+CFLAGS += -I$(NANOPB_DIR)
+
+all: server client
+
+clean:
+	rm -f server client fileproto.pb.c fileproto.pb.h
+
+%: %.c $(DEPS) fileproto.pb.h fileproto.pb.c
+	$(CC) $(CFLAGS) -o $@ $< $(NANOPB_DIR)/pb_decode.c $(NANOPB_DIR)/pb_encode.c fileproto.pb.c common.c
+
+fileproto.pb.c fileproto.pb.h: fileproto.proto $(NANOPB_DIR)/generator/nanopb_generator.py
+	protoc -ofileproto.pb $<
+	python $(NANOPB_DIR)/generator/nanopb_generator.py fileproto.pb
diff --git a/examples/network_server/README b/examples/network_server/README
new file mode 100644
index 00000000..7bdcbed5
--- /dev/null
+++ b/examples/network_server/README
@@ -0,0 +1,60 @@
+Nanopb example "network_server"
+===============================
+
+This example demonstrates the use of nanopb to communicate over network
+connections. It consists of a server that sends file listings, and of
+a client that requests the file list from the server.
+
+Example usage
+-------------
+
+user@host:~/nanopb/examples/network_server$ make        # Build the example
+protoc -ofileproto.pb fileproto.proto
+python ../../generator/nanopb_generator.py fileproto.pb
+Writing to fileproto.pb.h and fileproto.pb.c
+cc -ansi -Wall -Werror -I .. -g -O0 -I../.. -o server server.c
+    ../../pb_decode.c ../../pb_encode.c fileproto.pb.c common.c
+cc -ansi -Wall -Werror -I .. -g -O0 -I../.. -o client client.c
+    ../../pb_decode.c ../../pb_encode.c fileproto.pb.c common.c
+
+user@host:~/nanopb/examples/network_server$ ./server &  # Start the server on background
+[1] 24462
+
+petteri@oddish:~/nanopb/examples/network_server$ ./client /bin  # Request the server to list /bin
+Got connection.
+Listing directory: /bin
+1327119    bzdiff
+1327126    bzless
+1327147    ps
+1327178    ntfsmove
+1327271    mv
+1327187    mount
+1327259    false
+1327266    tempfile
+1327285    zfgrep
+1327165    gzexe
+1327204    nc.openbsd
+1327260    uname
+
+
+Details of implementation
+-------------------------
+fileproto.proto contains the portable Google Protocol Buffers protocol definition.
+It could be used as-is to implement a server or a client in any other language, for
+example Python or Java.
+
+fileproto.options contains the nanopb-specific options for the protocol file. This
+sets the amount of space allocated for file names when decoding messages.
+
+common.c/h contains functions that allow nanopb to read and write directly from
+network socket. This way there is no need to allocate a separate buffer to store
+the message.
+
+server.c contains the code to open a listening socket, to respond to clients and
+to list directory contents.
+
+client.c contains the code to connect to a server, to send a request and to print
+the response message.
+
+The code is implemented using the POSIX socket api, but it should be easy enough
+to port into any other socket api, such as lwip.
diff --git a/example/client.c b/examples/network_server/client.c
index e6e9a2e0..e6e9a2e0 100644
--- a/example/client.c
+++ b/examples/network_server/client.c
diff --git a/example/common.c b/examples/network_server/common.c
index 04a5aa85..04a5aa85 100644
--- a/example/common.c
+++ b/examples/network_server/common.c
diff --git a/example/common.h b/examples/network_server/common.h
index 8dab3b7c..8dab3b7c 100644
--- a/example/common.h
+++ b/examples/network_server/common.h
diff --git a/example/fileproto.options b/examples/network_server/fileproto.options
index 29a2ab0e..29a2ab0e 100644
--- a/example/fileproto.options
+++ b/examples/network_server/fileproto.options
diff --git a/example/fileproto.proto b/examples/network_server/fileproto.proto
index 3e70c492..3e70c492 100644
--- a/example/fileproto.proto
+++ b/examples/network_server/fileproto.proto
diff --git a/example/server.c b/examples/network_server/server.c
index 9a9c2644..9a9c2644 100644
--- a/example/server.c
+++ b/examples/network_server/server.c
diff --git a/examples/using_double_on_avr/Makefile b/examples/using_double_on_avr/Makefile
new file mode 100644
index 00000000..0b5383fa
--- /dev/null
+++ b/examples/using_double_on_avr/Makefile
@@ -0,0 +1,29 @@
+CFLAGS = -Wall -Werror -g -O0
+
+# Path to the nanopb root directory
+NANOPB_DIR = ../..
+DEPS = double_conversion.c $(NANOPB_DIR)/pb.h \
+	$(NANOPB_DIR)/pb_decode.c $(NANOPB_DIR)/pb_decode.h \
+	$(NANOPB_DIR)/pb_encode.c $(NANOPB_DIR)/pb_encode.h
+CFLAGS += -I$(NANOPB_DIR)
+
+all: run_tests
+
+clean:
+	rm -f test_conversions encode_double decode_double doubleproto.pb.c doubleproto.pb.h
+
+test_conversions: test_conversions.c double_conversion.c
+	$(CC) $(CFLAGS) -o $@ $^
+
+%: %.c $(DEPS) doubleproto.pb.h doubleproto.pb.c
+	$(CC) $(CFLAGS) -o $@ $< double_conversion.c \
+		$(NANOPB_DIR)/pb_decode.c $(NANOPB_DIR)/pb_encode.c doubleproto.pb.c
+
+doubleproto.pb.c doubleproto.pb.h: doubleproto.proto $(NANOPB_DIR)/generator/nanopb_generator.py
+	protoc -odoubleproto.pb $<
+	python $(NANOPB_DIR)/generator/nanopb_generator.py doubleproto.pb
+
+run_tests: test_conversions encode_double decode_double
+	./test_conversions
+	./encode_double | ./decode_double
+    
diff --git a/example_avr_double/README.txt b/examples/using_double_on_avr/README
index 0090d729..d9fcdfc6 100644
--- a/example_avr_double/README.txt
+++ b/examples/using_double_on_avr/README
@@ -1,3 +1,6 @@
+Nanopb example "using_double_on_avr"
+====================================
+
 Some processors/compilers, such as AVR-GCC, do not support the double
 datatype. Instead, they have sizeof(double) == 4. Because protocol
 binary format uses the double encoding directly, this causes trouble
@@ -9,7 +12,7 @@ platforms. The file double_conversion.c provides functions that
 convert these values to/from floats, without relying on compiler
 support.
 
-To use this method, you need to make two modifications to your code:
+To use this method, you need to make some modifications to your code:
 
 1) Change all 'double' fields into 'fixed64' in the .proto.
 
@@ -17,6 +20,6 @@ To use this method, you need to make two modifications to your code:
 
 3) Whenever reading a 'double' field, use double_to_float().
 
-The conversion routines should be as accurate as the float datatype can
+The conversion routines are as accurate as the float datatype can
 be. Furthermore, they should handle all special values (NaN, inf, denormalized
 numbers) correctly. There are testcases in test_conversions.c.
diff --git a/example_avr_double/decode_double.c b/examples/using_double_on_avr/decode_double.c
index 5802eca7..5802eca7 100644
--- a/example_avr_double/decode_double.c
+++ b/examples/using_double_on_avr/decode_double.c
diff --git a/example_avr_double/double_conversion.c b/examples/using_double_on_avr/double_conversion.c
index cf79b9a0..cf79b9a0 100644
--- a/example_avr_double/double_conversion.c
+++ b/examples/using_double_on_avr/double_conversion.c
diff --git a/example_avr_double/double_conversion.h b/examples/using_double_on_avr/double_conversion.h
index 62b6a8ae..62b6a8ae 100644
--- a/example_avr_double/double_conversion.h
+++ b/examples/using_double_on_avr/double_conversion.h
diff --git a/example_avr_double/doubleproto.proto b/examples/using_double_on_avr/doubleproto.proto
index d8b7f2db..d8b7f2db 100644
--- a/example_avr_double/doubleproto.proto
+++ b/examples/using_double_on_avr/doubleproto.proto
diff --git a/example_avr_double/encode_double.c b/examples/using_double_on_avr/encode_double.c
index cd532d46..cd532d46 100644
--- a/example_avr_double/encode_double.c
+++ b/examples/using_double_on_avr/encode_double.c
diff --git a/example_avr_double/test_conversions.c b/examples/using_double_on_avr/test_conversions.c
index 22620a6a..22620a6a 100644
--- a/example_avr_double/test_conversions.c
+++ b/examples/using_double_on_avr/test_conversions.c
diff --git a/examples/using_union_messages/Makefile b/examples/using_union_messages/Makefile
new file mode 100644
index 00000000..0f7b5206
--- /dev/null
+++ b/examples/using_union_messages/Makefile
@@ -0,0 +1,22 @@
+CFLAGS = -ansi -Wall -Werror -g -O0
+
+# Path to the nanopb root folder
+NANOPB_DIR = ../..
+DEPS = $(NANOPB_DIR)/pb_decode.c $(NANOPB_DIR)/pb_decode.h \
+       $(NANOPB_DIR)/pb_encode.c $(NANOPB_DIR)/pb_encode.h $(NANOPB_DIR)/pb.h
+CFLAGS += -I$(NANOPB_DIR)
+
+all: encode decode
+	./encode 1 | ./decode
+	./encode 2 | ./decode
+	./encode 3 | ./decode
+
+clean:
+	rm -f encode unionproto.pb.h unionproto.pb.c
+
+%: %.c $(DEPS) unionproto.pb.h unionproto.pb.c
+	$(CC) $(CFLAGS) -o $@ $< $(NANOPB_DIR)/pb_decode.c $(NANOPB_DIR)/pb_encode.c unionproto.pb.c
+
+unionproto.pb.h unionproto.pb.c: unionproto.proto $(NANOPB_DIR)/generator/nanopb_generator.py
+	protoc -ounionproto.pb $<
+	python $(NANOPB_DIR)/generator/nanopb_generator.py unionproto.pb
diff --git a/examples/using_union_messages/README b/examples/using_union_messages/README
new file mode 100644
index 00000000..7a1e75d4
--- /dev/null
+++ b/examples/using_union_messages/README
@@ -0,0 +1,52 @@
+Nanopb example "using_union_messages"
+=====================================
+
+Union messages is a common technique in Google Protocol Buffers used to
+represent a group of messages, only one of which is passed at a time.
+It is described in Google's documentation:
+https://developers.google.com/protocol-buffers/docs/techniques#union
+
+This directory contains an example on how to encode and decode union messages
+with minimal memory usage. Usually, nanopb would allocate space to store
+all of the possible messages at the same time, even though at most one of
+them will be used at a time.
+
+By using some of the lower level nanopb APIs, we can manually generate the
+top level message, so that we only need to allocate the one submessage that
+we actually want. Similarly when decoding, we can manually read the tag of
+the top level message, and only then allocate the memory for the submessage
+after we already know its type.
+
+
+Example usage
+-------------
+
+Type `make` to run the example. It will build it and run commands like
+following:
+
+./encode 1 | ./decode
+Got MsgType1: 42
+./encode 2 | ./decode
+Got MsgType2: true
+./encode 3 | ./decode
+Got MsgType3: 3 1415
+
+This simply demonstrates that the "decode" program has correctly identified
+the type of the received message, and managed to decode it.
+
+
+Details of implementation
+-------------------------
+
+unionproto.proto contains the protocol used in the example. It consists of
+three messages: MsgType1, MsgType2 and MsgType3, which are collected together
+into UnionMessage.
+
+encode.c takes one command line argument, which should be a number 1-3. It
+then fills in and encodes the corresponding message, and writes it to stdout.
+
+decode.c reads a UnionMessage from stdin. Then it calls the function
+decode_unionmessage_type() to determine the type of the message. After that,
+the corresponding message is decoded and the contents of it printed to the
+screen.
+
diff --git a/example_unions/decode.c b/examples/using_union_messages/decode.c
index b9f4af55..b9f4af55 100644
--- a/example_unions/decode.c
+++ b/examples/using_union_messages/decode.c
diff --git a/example_unions/encode.c b/examples/using_union_messages/encode.c
index e124bf91..e124bf91 100644
--- a/example_unions/encode.c
+++ b/examples/using_union_messages/encode.c
diff --git a/example_unions/unionproto.proto b/examples/using_union_messages/unionproto.proto
index d7c9de2d..d7c9de2d 100644
--- a/example_unions/unionproto.proto
+++ b/examples/using_union_messages/unionproto.proto