Add documentation for the OID scripts.

Make the commands print a short usage summary and add a README file that
explains the dependencies.

Change-Id: I0c3f0713749ecfca23afaa2b536ac70dbdd7db0a
Reviewed-on: https://boringssl-review.googlesource.com/2471
Reviewed-by: Adam Langley <agl@google.com>

crypto/obj/README

@@ -0,0 +1,37 @@
+OID information is generated via a series of perl scripts. In order, the full
+list of commands to run are:
+
+        perl objects.pl objects.txt obj_mac.num ../../include/openssl/obj_mac.h
+        perl obj_dat.pl ../../include/openssl/obj_mac.h obj_dat.h
+        perl obj_xref.pl obj_mac.num obj_xref.txt > obj_xref.h
+
+objects.txt contains the list of all built-in OIDs. It is processed by
+objects.pl to output obj_mac.num and obj_mac.h. obj_mac.num is the list of NID
+values for each OID. This is an input/output parameter so NID values are stable
+across regenerations. obj_mac.h is the header which defines macros for all the
+built-in OIDs in C.
+
+obj_mac.h is read by obj_dat.pl to generate obj_dat.h. obj_dat.h contains the
+ASN1_OBJECTs corresponding to built-in OIDs themselves along with lookup tables
+for search by short name, OID, etc.
+
+obj_mac.num and obj_xref.txt are read by obj_xref.pl to generate
+obj_xref.h. obj_xref.txt links signature OIDs to corresponding public key
+algorithms and digests. obj_xref.h contains lookup tables for querying this
+information in both directions.
+
+Dependency graph:
+
+                        objects.txt
+                            |
+                            V
+                       [objects.pl] <--+
+                         /      \      |
+                        V        V     |
+                  obj_mac.h    obj_mac.num  obj_xref.txt
+                      |              \      /
+                      V               V    V
+                 [obj_dat.pl]      [obj_xref.pl]
+                      |                  |
+                      V                  V
+                  obj_dat.h         obj_xref.h

crypto/obj/obj_dat.pl

@@ -1,9 +1,15 @@
-#!/usr/local/bin/perl
+#!/usr/bin/env perl
 
 # fixes bug in floating point emulation on sparc64 when
 # this script produces off-by-one output on sparc64
 use integer;
 
+if (scalar @ARGV != 2)
+	{
+	print "Usage: perl obj_dat.pl ../../include/openssl/obj_mac.h obj_dat.h\n";
+	exit 1;
+	}
+
 sub obj_cmp
 	{
 	local(@a,@b,$_,$r);
@@ -170,7 +176,7 @@ foreach (sort obj_cmp @a)
 print OUT <<'EOF';
 /* THIS FILE IS GENERATED FROM objects.h by obj_dat.pl via the
  * following command:
- * perl obj_dat.pl obj_mac.h obj_dat.h */
+ * perl obj_dat.pl ../../include/openssl/obj_mac.h obj_dat.h */
 
 /* Copyright (C) 1995-1997 Eric Young (eay@cryptsoft.com)
  * All rights reserved.

crypto/obj/obj_xref.pl

@@ -1,7 +1,13 @@
-#!/usr/local/bin/perl
+#!/usr/bin/env perl
 
 use strict;
 
+if (scalar @ARGV != 2)
+	{
+	print "Usage: perl obj_xref.pl obj_mac.num obj_xref.txt > obj_xref.h\n";
+	exit 1;
+	}
+
 my %xref_tbl;
 my %oid_tbl;
 
@@ -60,7 +66,9 @@ my $pname = $0;
 $pname =~ s|^.[^/]/||;
 
 print <<EOF;
-/* AUTOGENERATED BY $pname, DO NOT EDIT */
+/* THIS FILE IS GENERATED FROM obj_xref.txt by obj_xref.pl via the
+ * following command:
+ * perl obj_xref.pl obj_mac.num obj_xref.txt > obj_xref.h */
 
 typedef struct
 	{

crypto/obj/objects.pl

@@ -1,4 +1,10 @@
-#!/usr/local/bin/perl
+#!/usr/bin/env perl
+
+if (scalar @ARGV != 3)
+	{
+	print "Usage: perl objects.pl objects.txt obj_mac.num ../../include/openssl/obj_mac.h\n";
+	exit 1;
+	}
 
 open (NUMIN,"$ARGV[1]") || die "Can't open number file $ARGV[1]";
 $max_nid=0;
@@ -121,7 +127,7 @@ open (OUT,">$ARGV[2]") || die "Can't open output file $ARGV[2]";
 print OUT <<'EOF';
 /* THIS FILE IS GENERATED FROM objects.txt by objects.pl via the
  * following command:
- * perl objects.pl objects.txt obj_mac.num obj_mac.h */
+ * perl objects.pl objects.txt obj_mac.num ../../include/openssl/obj_mac.h */
 
 /* Copyright (C) 1995-1997 Eric Young (eay@cryptsoft.com)
  * All rights reserved.